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produce a typeset-quality copy containing integrated graphics. 
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Preface 


The VMS DECwindows Transport Manual provides information needed to 
write a DECwindows transport interface that runs under VMS 

Version 5.3 and to load it under DECwindows. Digital makes no guarantee 
that transport interfaces written using these guidelines will execute 
without modification on future versions of the operating system. Because 
this is the first version of the VMS system that supports user-written 
transport layers, it is likely that the existing programming interface will 
change. 





Intended Audience 


This document is intended for programmers who need information about 
the components and interfaces of the VMS DECwindows transport 

layer. It describes the theory-of-operation and interconnection of each 
component of the VMS DECwindows transport layer. It also describes the 
recommended coding procedures that you should follow when augmenting 
the DECwindows transport layer with a third-party transport. 


You should read this document before modifying or replacing the VMS 
DECwindows transport. 


This document assumes that you are familiar with the overall design of 
the VMS DECwindows implementation. 





Document Structure 


The VMS DECwindows Transport Manual is organized into the following 
chapters: 


e¢ Chapter 1 provides an overview of the VMS DECwindows transport 
layer. 


e Chapter 2 describes how X11 protocol requests, events, errors, and 
replies are generated and transmitted in the VMS DECwindows 
environment. Although the transport layer itself does not interpret the 
data that it transfers, you should read this chapter to become familiar 
with how the transport layer supports the X11 protocol. 


¢ Chapter 3 describes the theory-of-operation and interconnection of each 
component of the VMS DECwindows transport layer. This chapter 
includes a description of the functions performed by the common and 
specific components and how they interact. 


e¢ Chapter 4 describes a walk-through of typical transport layer 
activities. 


¢ Chapter 5 describes the transport-common routines that a transport- 
specific component needs to call. You should read this chapter to 
become familiar with the operation and use of these routines. 


e Chapter 6 describes the transport-specific routines that you must 
implement if you write your own transport-specific component. 
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e Chapter 7 describes the transport-layer utility routines that you can 
use. These routines are provided for your convenience; there is no 
requirement that you use them, but you must implement similar 
functions. 


¢ Chapter 8 describes a cookbook approach to writing your own 
transport-specific routines. The chapter includes a sample BLISS-32 
code example for each of the transport-specific routines that you 
must write. Your own implementation of these routines may differ 
depending on your chosen network service. 


Associated Documents 


For more information about DECwindows, see the VMS DECwindows 
documentation set. 





Conventions 


The following conventions are used in this manual: 


In examples, a horizontal ellipsis indicates one of the 
following possibilities: 


¢ Additional optional arguments in a statement 
have been omitted. 


¢ The preceding item or items can be repeated one 
or more times. 

* Additional parameters, values, or other 
information can be entered. 


A vertical ellipsis indicates the omission of items from 
a code example or command format; the items are 
omitted because they are not important to the topic 
being discussed. 


() In format descriptions, parentheses indicate that, if 
you choose more than one option, you must enclose 
the choices in parentheses. 


[] In format descriptions, brackets indicate that whatever 
is enclosed within the brackets is optional; you can 
select none, one, or all of the choices. (Brackets are 
not, however, optional in the syntax of a directory 
name in a file specification or in the syntax of a 
substring specification in an assignment statement.) 


{} In format descriptions, braces surround a required 
choice of options; you must choose one of the options 
listed. 


boldface text Boldface text represents the introduction of a new 
term or the name of an argument, an attribute, or a 
reason. 


italic text Italic text represents information that can vary 
in system messages (for example, Internal error 
number). 


UPPERCASE TEXT 


numbers 
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Uppercase letters indicate that you must enter a 
command (for example, enter OPEN/READ), or they 
indicate the name of a routine, the name of a file, the 
name of a file protection code, or the abbreviation for 
a system privilege. 

Hyphens in coding examples indicate that additional 
arguments to the request are provided on the line that 
follows. 


Unless otherwise noted, all numbers in the text are 
assumed to be decimal. Nondecimal radixes—binary, 
octal, or hexadecimal—are explicitly indicated. 


xiii 


1 Overview of the VMS DECwindows Transport Layer 


The VMS DECwindows transport layer is separated into transport- 
common and transport-specific components. The routines that comprise 
the transport-common layer are network independent and are used to 
buffer and queue data to be sent between a client and server. The 
transport-common routines then call routines that are specific to a 
particular network service, such as DECnet and TCP/IP, to actually move 
the data across the network. 


The transport-specific routines perform the following functions: 
e Initialize (attach) a specific network service 

e Connect a client to a server 

¢ Write data to the network service 

¢ Read data from the network service 


e Close a connection and release connection resources 


To implement your own transport layer, you must write the transport- 
specific routines to support your particular network service and link them 
as a VMS shareable image that can be accessed by the transport-common 
component. 


Chapter 8 includes examples of transport-specific routines that implement 
a TCP/IP transport layer for DECwindows. You can use these code 
examples as a starting point when writing your own transport-specific 
routines. 


Depending upon the network service on which you are building, you will 
probably find that the routines that initialize a transport and establish a 
connection require the most modification. You may also find that routines 
that primarily insert and remove buffers from the queues can be used with 
minimal changes. 


The remainder of this chapter provides an overview of the VMS 
DECwindows transport layer. Subsequent chapters describe the transport 
layer components and their interconnection in greater detail. 





1.1 The Transport Layer Function 


The function of the transport layer is to move X Window System, 

Version 11 (X11) protocol requests between an application, called the client, 
and the X11 server in an efficient manner. The transport layer transmits 
data over network transports. VMS DECwindows currently supports 
three network transports: DECnet, TCP/IP, and a high-performance local 
transport. 


Overview of the VMS DECwindows Transport Layer 
1.1 The Transport Layer Function 


In the X11 environment, the mechanism for sending information from a 
client to the server is by way of a “connection” to the server. Creating a 
client/server connection is known as opening a display; when you open a 
display, you open a connection. 


The transport layer is a general data-transfer mechanism; it does not 
interpret or understand the format of the data that it transfers. The 
transport layer operates symmetrically on both ends of the client/server 
connection: it buffers and sends output requests from Xlib to the server 
and buffers and sends input events, errors, and replies to Xlib. The buffers 
are maintained in a series of communication queues. 


The transport layer maintains status (communication context) on a per- 
connection basis. 


1.2 Transport Common/Specific Architecture 


The VMS DECwindows transport layer is installed as part of 

the DECwindows common component; that is, the transport 

layer is always installed when DECwindows is installed. The 
DECwindows DECW$STARTUP.COM procedure installs all of 

the transport images—DECW$TRANSPORT_COMMON.EXE, 
DECW$TRANSPORT_LOCAL.EXE, DECW$TRANSPORT_DECNET.EXE, 
and DECW$TRANSPORT_TCPIPEXE—each time DECwindows is 
started. 


Xlib and the server both initialize and attach a network-specific transport 
for their respective side of the connection. 


The transport layer is separated into transport-common and transport- 
specific functions. The transport-common functions, which are contained 
in DECW$TRANSPORT_COMMON.EXE, provide the generic services 
needed by Xlib or the server. The transport-common functions buffer 
and queue the data to be sent between the client and server and then 
call functions in the various images (DECW$TRANSPORT_LOCAL.EXE, 
DECW$TRANSPORT_DECNET.EXE, DECW$TRANSPORT_TCPIP.EXE) 
that are specific to a particular transport service, such as local, DECnet, 
and TCP/IP, respectively, to actually move the data. 


This architecture allows the transport-common component to present a 
common buffer/queue interface to other DECwindows components while 
the transport-specific component “hides” the details of how data is actually 
transmitted. 


The transport-common/transport-specific architecture is particularly 
important because the transport layer must be flexible enough to 
efficiently support two types of client/server connections: 


e Ifthe client and server are executing on two different VMS systems, a 
transport image physically executes on both the client system and the 
server system. The two transports then establish a network connection 
between themselves to pass the data. The transport layer buffers 
data to reduce the number of required network round-trips and their 
associated overhead. 


This is called a remote connection. 


Overview of the VMS DECwindows Transport Layer 
1.2 Transport Common/Specific Architecture 


e Ifthe client and server are executing on the same VMS system, there 
is no need to establish a network connection, but the client must still 
open a logical connection to the server to pass data. This is called a 
local connection. Xlib and the server both initialize the transport- 
common code for their respective side of the client/server connection 
just as they would in the case of a remote connection. However, Xlib 
and the server then attach a local transport to transmit data. 


The VMS DECwindows transport layer establishes remote or local 
connections to a server based on the display name argument passed by a 
client in the Xlib OPEN DISPLAY routine or through information specified 
in a SET DISPLAY command. (By passing a null value in the call to 

the OPEN DISPLAY routine, a client need not hard code the display 
name. See the VMS DECwindows Xlib Programming Volume for more 
information.) 


In a remote transport connection, a node name other than “0” indicates 
that a remote workstation node in the network is to be used as the display; 
the client application and the server do not execute on the same physical 
machine. The transport layer performs its buffering functions and calls a 
transport such as DECnet to send the data across the network, as shown 
in Figure 1-1. 


Overview of the VMS DECwindows Transport Layer 
1.2 Transport Common/Specific Architecture 


Figure 1-1 Remote Transport Connection 
















Client runs on 
remote node and 

opens connection 
to WORK1. 


The transport on the client side 
of the connection establishes a 
connection to the transport on 
the server side of the connection. 


The transport (both sides) buffers 
the data being sent. 


Client appears 
here and accepts 
input from this 
keyboard. 
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Overview of the VMS DECwindows Transport Layer 
1.2 Transport Common/Specific Architecture 


In a local transport connection, a node name of “0” indicates that the 
client and server are executing on the same hardware, as shown in 
Figure 1-2. There is no need for the transport layer to send the data 
across the network, but Xlib and the server must still communicate. The 
local transport layer implements a shared-memory transport. The shared- 
memory transport performs functions that are similar to those performed 
by the DECnet or TCP/IP transport-specific components, but does not 
incur the network overhead. 


Figure 1-2 Local Transport Connection 


Client runs 
here and accepts 
input from this 
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2 X11 Protocol Overview 


The X Window System, Version 11 (X11) standard defines a common 
protocol for all communications between client applications and 
implementations of the X11 server. This standard protocol makes it 
possible to mix client/server pairs from different operating-system and 
vendor environments. 


The protocol defines the format of the data, such as the request, reply, 
error, and event formats, that is passed between the client and server; it 
does not dictate the mechanism for transporting this data. The protocol 
nests inside transport mechanisms that move the protocol requests 
between clients and servers. 


This chapter describes how X11 protocol requests, events, errors, 

and replies are generated and transmitted in the VMS DECwindows 
environment. You should read this chapter to become familiar with how 
the transport layer supports the X11 protocol. Later chapters describe the 
transport layer’s architecture and role in supporting the X11 protocol in 
greater detail. 


For more information about the X11 protocol, see the X Window System C 
Library and Protocol Reference by Robert W. Scheifler, James Gettys, and 
Ron Newman. 


2.1 Generating a Protocol Request 


When a DECwindows client program needs to generate output on a screen 
connected to a display, the client calls an Xlib or XUI Toolkit routine 

to perform the output. Xlib translates these routines into one or more 
protocol requests. The protocol request is sent from a client to server to 
invoke some operation in the server. Requests may be synchronous (the 
client waits until the server sends a reply packet) or asynchronous (no 
reply is generated and the client may send more requests). 


The protocol request is either one of the core protocol requests or a protocol 
request that is interpreted by an extension. The format of the core protocol 
request is predefined to ensure portability of core requests across various 
implementations of the X Window System. The format of the protocol 
request is shown in Figure 2-1. 
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X11 Protocol Overview 
2.1 Generating a Protocol Request 


Figure 2-1 Protocol Request Format 


Length Field Data Bytes (256Kb maximum split 
(including across buffers; 16Kb typically in 


opcode) 1 buffer for VMS) 
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Protocol Request Header 


Note: 
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Every request consists of a 4-byte header, which contains an 8-bit “major” 
opcode, a spare data byte used that is usually used for the “minor” opcode 
of an extension, and a 16-bit length field. The header is followed by zero 
or more additional bytes of data; unused bytes are not required to be zero, 
except in a few special cases such as image text. 


The core protocol requests use only seven of the eight available bits of 
the opcode field in the request header; major opcodes 0 through 127 are 
reserved for core requests. Extensions use all eight bits, and opcodes 128 
through 255 are reserved for extensions. 


Because the 128 opcodes available for extensions could be consumed fairly 
quickly, extensions usually have an additional 8-bit minor opcode encoded 
in the spare data byte of the request header. This minor opcode increases 
the number of requests that can be associated with a major opcode. By 
convention, each extension uses one major opcode. 


The placement and interpretation of the minor opcode, and all 
other nonheader fields in extension requests, are not defined by 
the core protocol. 


The length field is a 16-bit value that defines the total number of 
longwords in the request, including the header. For example, if the value 
of the length field was 4096, multiply 4096 times 4 to compute a request 
length of 16,384 bytes. The maximum size of a protocol request that a 
server is willing to accept is server dependent; the server communicates 
this maximum request length to the client as part of the connection setup 
when a client opens a connection. 


The length field must be exactly the number of longwords in the request. 
If the specified length is shorter or longer than the actual length, the 
protocol is corrupted and the default error handler may generate a fatal or 
nonfatal error. Under other circumstances an inconsistent length field can 
hang the server. 


X11 Protocol Overview 
2.2 Xlib Output Buffering and Synchronization 


2.2 Xlib Output Buffering and Synchronization 


Most of the Xlib routines add protocol requests to an output buffer; these 
protocol requests are later sent to the server when the buffer fills or is 
explicitly flushed by the client. The transport layer maintains the buffers 
on a per-connection basis. If a client explicitly flushes a buffer, only the 
output requests for that connection are affected; output buffered for other 
connections, either to the same or a different server, is not affected. 


The total number of available output buffers is set by the server and Xlib 
when the transport layer is initialized. The Xlib output buffers for an 
individual connection are established when the connection to the server is 
opened. The format of the output request buffer is shown in Figure 2-2. 


Figure 2-2 Output Buffer Containing a Protocol Request 


16 31 


Length Field Data Bytes (256Kb maximum split 
(including across buffers; 16Kb typically in 
opcode) 1 buffer for VMS) 


VMS Data Buffer: Data Buffer 
Structure | One or more protocol requests per 
Header buffer for VMS implementation 





Note: 
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The number of protocol requests that Xlib sends in a single output buffer 
depends on the amount of data that is associated with each request. 
Because the VMS implementation of Xlib tries not to split protocol 
requests across output buffers, Xlib adds requests to a buffer until a 
protocol request does not fit completely within the remaining space. Xlib 
then flushes the current buffer and adds the waiting protocol request to 
the head of a new buffer. 


The server negotiates the size of the largest request for each 
connection when the connection is opened. The VMS DECwindows 
server accepts up to a 16Kb protocol request. 


The maximum size of a protocol request allowed by the X11 
protocol is 256Kb (65,535 times 4). The core protocol allows Xlib 
to split protocol requests across output request buffers, and other 
Xlib implementations are likely to do this. It is therefore possible 
that a read request will not return a complete protocol message 
and Xlib and the server must handle this case. 
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2.3 


2.4 


X11 Protocol Overview 
2.2 Xlib Output Buffering and Synchronization 


Xlib provides routines with which clients can control output buffering. If 
you do not want an output request to wait for the buffer to fill, you can 
follow it with an explicit call to a routine such as FLUSH, which sends all 
buffered output for a connection. 


Xlib also includes routines that allow clients to synchronize output 
requests. Xlib accomplishes this synchronization by immediately flushing 
the client’s Xlib output buffer after each output request and then calling a 
synchronization routine that generates a return. 


Transporting the Protocol Request 


Note: 


Once the transport layer receives the output request buffer from Xlib, it 
arranges to have the data transmitted to the server. The transport layer 
on the server side of the connection receives the data and notifies the 
server that data is available. 


The Xlib output request buffer is actually a transport layer 
communication buffer (XTCB). The XTCB data structure is 
described in Section 3.1.4. 


The connection could be across the network to the display, or within a 
workstation in the case where the client and server have established a 
local connection. The networking service is assumed to be reliable; Xlib, 
the transport layer, and the server assume that the data arrives intact and 
error-free. 


The transport layer notifies the scheduler at user-AST level that it has 
data available for a connection. The dispatcher calls the transport layer to 
get the data. 





Client Input 
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Input to clients comes in three forms: input events, errors, and replies. An 
event packet is the X11 protocol message sent from a server to a client that 
gives information about some event in the server, such as a windowing 
operation, a keyboard key transition, or a mouse movement. Clients can 
also use request packets (XSendEvent) to send events to another client by 
way of the server. An event packet consists of exactly 32 bytes. 


An error packet is the X11 protocol message sent from a server to a client 
that indicates an error state in the server. An error packet consists of 
exactly 32 bytes. 


A reply packet is the X11 protocol message sent from a server to a client 
in response to a client protocol request that generates data (for example, 
GetImage). A reply can be any length with a maximum size of some 

16 gigabytes. 


| 


2.4.1 


Handling Input 


X11 Protocol Overview 
2.4 Client Input 


Most input events are reported to clients relative to windows. Events 

are usually sent to the smallest enclosing window in which the pointer is 
located that is interested in the type of event being sent. It is also possible 
to assign the keyboard input focus to a specific window. When the input 
focus is attached to a window, keyboard events go to the client that has 
selected input on that window, rather than to the window in which the 
pointer is located. 


The input component of the server services the XEvent queue and 
interacts with the window manager to determine which window is 
associated with the position recorded in the input queue entry. The 
window ID to which the event is to be delivered is then recorded in the 
event packet. The input component calls the events component to send the 
input events to clients that want to know about input in this window ID. 


Client programs can use the event_mask argument of the XSelectInput 
routine to select the events for which they want to receive notification. The 
server does not send events to a client unless the client has specifically 
asked to be informed of that type of event. One exception to this rule is 
that one client can use the XSendEvent routine to force events to be sent 
to other clients. 


An interest list is attached to the window ID data structure. Each entry 
on the interest list describes filtering parameters defined by the client’s 

event masks. If there are multiple windows interested in the event, the 
event is sent to multiple windows. 


The events component calls the transport layer to transmit the processed 
input event packets to the Xlib input queue. The transport layer buffers 
the events packets on a per-connection basis and delivers them to the 
Xlib input queues. As in the case for output, the transport layer does 
not interpret the data. Input normally arrives at the client as an I/O 
completion. Typically, the client processes the input event and generates 
output requests. 


The input event is retained by Xlib until a client requests the next, or the 
next matching, event. It is the responsibility of the client to request the 
event; if the client does not request the event, the event remains in the 
queue. 


Xlib provides routines such as XPeekIfEvent and XCheckIfEvent that 
client programs can call to check for particular types of events on their 
respective input queues. These routines require client programs to supply 
a procedure that determines if the next event in the queue matches the 
one that the client wants. 
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3 Transport Layer Architecture 


This chapter describes the theory-of-operation and interconnection of each 
component of the VMS DECwindows transport layer. The relationship 
between the transport-common and transport-specific layers, as described 
in Section 3.3, is of particular importance. 


The chapter begins with a description of the transport layer data 
structures. 


3.1 Transport Layer Data Structures 


The transport layer data structures maintain the state of the transport 
and each of the established connections. The transport layer data 
structures are created in stages as the transport-common code is 
initialized, a transport-specific mechanism is attached, and connections 
are established. 


The XTPB, IXTCC, and XTDB data structures are allocated from memory 
pages that have user-mode read access/executive-mode write access 
(UREW) to prevent modification by less privileged access levels, including 
the transport-specific code that runs in user mode. The transport-common 
code depends on the accuracy of the contents of the XTPB, IXTCC, and 
XTDB data structures. 


The transport layer data structures are described in Table 3-1. 


Table 3-1 Transport Layer Data Structures 





Write 
Access 
Name When Created Mode Description 
XTPB Initialization exec Transport parameter block (XTPB) 
Transport attach contains default transport parameters. 
Connection open There is a three-level hierarchy of 
XTPB data structures. 
IXTCC Connection open exec Internal transport communications 


context (IXTCC) describes an 
established connection for executive- 
mode routines within the transport 
layer. The IXTCC is used by executive- 
mode routines to store protected 

data. 


(continued on next page) 
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Table 3-1 (Cont.) Transport Layer Data Structures 


Name 


XTCC 


XTDB 


XTCQ 


XTCB 


XTFT 


When Created 


Connection open 


Transport attach 


Connection open 


Connection open 


Transport attach 


Write 
Access 
Mode 


user 
exec 


exec 


user 
exec 


user 
exec 


exec 


Description 


Transport communications context 
(XTCC) describes an established 
connection. The XTCC is used to pass 
user-mode data to executive-mode 
routines. The XTCC may be modified 
by user-mode code and is visible to 
either the server or Xlib. 


Transport descriptor block (XTDB) 
describes each attached transport. 


Transport communication queue 
(XTCQ) contains six per-connection 
communication queues and their 
states. 


Transport communication buffers 
(XTCB) pass data in the transport 
layer. 


Transport function table (XTFT) 
contains the addresses of the 
transport-specific routines. The XTFT 
is the transport-common code’s link to 
the transport-specific code. 


The transport-common code creates the global XTPB structure at 
initialization time. The transport-common DECW$XPORT_ATTACH_ 
TRANSPORT routine creates XTDB, XTPB, and XTCB data structures, 
as shown in Figure 3-1. The XTCC, XTCQ, and XTCB data structures 
are allocated from memory pages that are user-writable so that routines 
running in either user or executive mode can modify them. 


Transport Layer Architecture 
3.1 Transport Layer Data Structures 


Figure 3-1 Transport Attach Data Structures 


Global XTPB 
(1 in common transport) 


= 


Transport XTPB XTDB 
(1 per transport) (1 per transport) 
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The transport-common open routine creates IXTCC and XTPB data 
structures. The transport-specific connection open routine creates XTCC, 
XTCQ, and XTCB data structures, as shown in Figure 3-2. 
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Figure 3-2 Transport Connection Open Data Structures 
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The transport-specific connection open routine also creates XTCB data 
structures, as shown in Figure 3-3. 


Transport Layer Architecture 
3.1 Transport Layer Data Structures 


Figure 3-3 Transport Connection Open XTCB Data Structures 
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XTCQ 
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The shaded areas of Figure 3—4 show the transport layer data structures 
that have user-mode read access/executive-mode write access. 


Transport Layer Architecture 
3.1 Transport Layer Data Structures 





Figure 3-4 Transport Data Structures 
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3.1.1 XTPB Data Structure 


When the transport layer is initialized, the transport-common code creates 
a global transport parameter block (XTPB). data structure that contains 
default parameters. The default parameters are inherited by every 
network-specific transport that is subsequently attached. The attached 
transport can override the defaults. 


Three levels of XTPB data structures are eventually built: 
e A global XTPB data structure 
e A transport-specific XTPB data structure 


e Aconnection-specific XTPB data structure 


The contents of the global XTPB data structure are copied to the transport- 
specific XTPB data structure when a transport is attached, and from the 
transport-specific XTPB data structure to a connection-specific XTPB 
data structure when a connection is established. The server and Xlib can 
override this inheritance of XTPB parameter values. After an XTPB has 
been created, changes to its parent’s values do not change its values. 


All XTPB data structures are allocated from memory pages that have 
user-mode read access/executive-mode write access (UREW) to protect 
them from modification by any less privileged access mode. 


The XTPB data structure is shown in Figure 3-5. 
Figure 3-5 XTPB Data Structure 
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XTPB$L_I_TIMEOUT 
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Figure 3-5 (Cont.) XTPB Data Structure 
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Table 3—2 shows the contents of the XTPB data structure. 
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Table 3-2 XTPB Data Structure 


Field Use 

XTPB$A_FLINK Reserved for use by Digital. 
XTPB$A_BLINK Reserved for use by Digital. 
XTPB$W_SIZE Total length of this XTPB in bytes. 
XTPB$B_TYPE Constant 255. 

XTPB$B_SUBTYPE Constant DECW$C_DYN_XTPB (7). 
XTPB$W_FLAGS See the following list. 


The following fields are defined within XTPB$W_FLAGS: 


XTPB$V_MODE Type of transport connection. Possible values 
are: 


* DECW$K_XPORT_REMOTE_SERVER (0) 
* DECW$K_XPORT_REMOTE_CLIENT (1) 
* DECW$K_XPORT_LOCAL_SERVER (2) 

* DECW$K_XPORT_LOCAL_CLIENT (3) 


XTPB$V_VALID If 1, this XTPB is valid. 


XTPB$W_DISPLAY_NUM The server number. Valid only when the transport 
caller is a server. 


XTPB$A_I_NOTIFY_RTNADR Address of an AST routine to call for input 
notification. 

XTPB$L_IL_NOTIFY_RTNPRM A longword value to be passed to the input 
notification AST routine. 


XTPB$A_O_NOTIFY_RTNADR Address of an AST routine to call for output 
notification. 
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Table 3-2 (Cont.) XTPB Data Structure 


Field 


XTPB$L_O_NOTIFY_RTNPRM 


XTPB$SW_IN_EFN 
XTPB$W_ON_EFN 
XTPB$W_SRP_SIZE 
XTPB$W_LRP_SIZE 
XTPB$L_I_TIMEOUT 
XTPB$W_I_SRP_COUNT 
XTPB$W_I_LRP_COUNT 
XTPB$W_O_SRP_COUNT 


XTPB$W_O_LRP_COUNT 


XTPB$L_O_TIMEOUT 


XTPB$L_I_TICKS 


XTPB$L_O_TICKS 


Use 


Argument to be passed to the output notification 
AST routine. 


Event flag to be set as part of input notification. If 
0, no flag is set. 

Event flag to be set as part of output notification. 
lf 0, no flag is set. 

Size, in bytes, of the data area of a small XTCB. 
Size, in bytes, of the data area of a large XTCB. 


Number of milliseconds that a common transport 
waits for a blocking input function to complete. If 
0, the common transport waits indefinitely. 


Number of small XTCBs to allocate for input 
operations. 


Number of large XTCBs to allocate for input 
operations. 


Number of small XTCBs to allocate for output 
operations. 


Number of large XTCBs to allocate for output 
operations. 


Number of milliseconds that a common transport 
waits for a blocking output function to complete. 
if 0, the common transport waits indefinitely. 
XTPB$L_I_TIMEOUT converted to ticks of the 
internal watchdog timer. 


XTPB$L_O_TIMEOUT converted to ticks of the 
internal watchdog timer. 


Some fields in the global XTPB have hard-coded defaults that provide a 
minimal working environment. Xlib and the server change these values 
for better performance when they initialize a transport. The global XTPB 
defaults are shown in Table 3-3. 


Table 3-3 XTPB Default Values 





Field 
XTPB$W_LRP_SIZE 


XTPBSW_SRP_SIZE 


Default 
Value 


16384 


1408 


Description 


Default large XTCB size. The minimum 
and maximum values are 16 and 65408, 
respectively. 


Default small XTCB size. The minimum 
and maximum values are 16 and 65408, 
respectively. 
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Table 3—3 (Cont.) XTPB Default Values 
Default 
Field Value Description 
XTPB$W_ON_EFN 0 Do not set an event flag on output. 
XTPBS$W_IN_EFN 0 Do not set an event flag on input. 
XTPBS$L_|_TIMEOUT 0 Do not time out. 
and 
XTPB$L_O_TIMEOUT 
XTPB$W_I_SRP_ 8 The total number of small input XTCBs. The 
COUNT minimum and maximum values are 0 and 128, 
respectively. 
XTPBSW_I_LRP_ 1 The total number of large input XTCBs. The 
COUNT minimum and maximum values are 0 and 128, 
respectively. 
XTPB$W_O_SRP_ 8 The total number of small output XTCBs. The 
COUNT minimum and maximum values are 0 and 128, 
respectively. 
XTPB$W_O_LRP_ 1 The-total number of large output XTCBs. The 
COUNT minimum and maximum values are 0 and 128, 


3.1.2 


respectively. 


IXTCC Data Structure 


The internal transport communications context (IXTCC) data structure 
is created when a connection is created and describes the established 
connection. There are actually two per-connection structures that store 


the 


communications context: 


The IXTCC data structure is allocated from memory pages that have 
user-mode read access/executive-mode write access (UREW). On the 
client side of the connection, the transport-common DECW$XPORT_ 
OPEN routine creates one IXTCC data structure per connection; on 
the server side of the connection, a transport-specific routine (such as 
the sample TRANSPORT_READ_AST routine described in Chapter 6) 
creates one IXTCC data structure per connection. 


The common transport uses the IXTCC structure to refer to a 
connection. The IXTCC structure exists during the lifetime of a 
connection. 


An XTCC data structure is user-modifiable. The server and Xlib use 
the XTCC to identify a connection when calling the transport layer. 
The XTCC structure exists during the lifetime of a connection. 


The IXTCC data structure is shown in Figure 3-6. 
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Figure 3-6 IXTCC Data Structure 
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Figure 3-6 (Cont.) 


IXTCC Data Structure 
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Table 3—4 shows the contents of the [IXTCC data structure. 


Table 3-4 IXTCC Data Structure 





Field 
IXTCC$A_FLINK 


IXTCC$A_BLINK 


IXTCC$W_SIZE 
IXTCC$B_TYPE 
IXTCC$B_SUBTYPE 
IXTCC$A_TCQ 
IXTCC$A_TPB 
IXTCC$A_TDB 
IXTCC$A_TCC 


IXTCC$A_USER_REGION 
IXTCC$A_BUFFER_REGION 
IXTCC$L_ICI 


IXTCC$A_IW_QUEUE 


IXTCC$A_IFS_QUEUE 


IXTCC$A_IFL_QUEUE 


Use 
Forward, absolute pointer to the next IXTCC in 
the XTDB’s queue of IXTCCs. 


Backward, absolute pointer to the previous 
IXTCC in the XTDB’s queue of IXTCCs. 


Length of IXTCC in bytes. 

Constant 255. 

Constant DECW$C_DYN_IXTCC (8). 
Address of XTCQ used by this connection. 
Address of XTPB private to this connection. 
Address of XTDB that owns this connection. 


Address of XTCC associated with this 
connection. 

Range of addresses allocated by 
DECW$XPORT_ALLOC_INIT_QUEUES. 
Range of addresses for communication 
buffers. 

Internal connection identifier. IXTCC$L_ICI is 
a protected copy of XTCC$L_ICI. 


Address of input work queue in the XTCQ. 
For clients this is the event work queue; for 
servers this is the request work queue. 


Address of the small XTCB input free queue in 
the XTCQ. 


Address of the large XTCB input free queue in 
the XTCQ. 
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Table 3—4 (Cont.) IXTCC Data Structure 


Field 
IXTCC$A_OW_QUEUE 


IXTCC$A_OFS_QUEUE 
IXTCC$A_OFL_QUEUE 


IXTCC$A_TCQ_FLAGS 
IXTCC$L_IWQ_FLAG 


IXTCC$L_IFSQ_FLAG 
IXTCC$L_IFLQ_FLAG 
IXTCC$L_OWQ_FLAG 
IXTCC$L_OFSQ_FLAG 
IXTCC$L_OFLQ_FLAG 


IXTCC$W_SCREEN 
IXTCCSW_UNIT 
IXTCC$Q_XPORT_RESERVED 


IXTCC$L_DEC_RESERVED 
IXTCC$A_XPORT_TABLE 


XTCC Data Structure 


Use 


Address of the output work queue in the 
XTCQ. For clients this is the request work 
queue; for servers this is the event work 
queue. 


Address of the small XTCB output free queue 
in the XTCQ. 


Address of the large XTCB output free queue 
in the XTCQ. 


Address of the flags longword in the XTCQ. 


Bit position of the input work queue notification 
request flag in the flags longword in the XTCQ. 


Bit position of the small XTCB input free queue 
notification request flag. 


Bit position of the large XTCB input free queue 
notification request flag. 


Bit position of the output work queue 
notification request flag. 


Bit position of the small XTCB output free 
queue interest flag. 


Bit position of the large XTCB output free 
queue interest flag. 


Reserved for use by Digital. 
Reserved for use by Digital. 


Quadword reserved for use by specific 
transport. 


Reserved for use by Digital. 


Address of XTFT structure for this specific 
transport. 


As described in Section 3.1.2, the transport communications context 
(XTCC) data structure describes an established connection. The server and 
Xlib use the XTCC to identify a connection when calling the DECwindows 
transport layer. The XTCC structure exists during the lifetime of a 
connection. This is a user-writable structure. 


The XTCC data structure is shown in Figure 3-7. 
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Figure 3-7 XTCC Data Structure 
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Figure 3-7 (Cont.) XTCC Data Structure 
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Table 3-5 XTCC Data Structure 


Field Use 

XTCC$A_FLINK Reserved for use by Digital. 
XTCC$A_BLINK ~ Reserved for use by Digital. 
XTCC$W_SIZE Length of XTCC in bytes. 
XTCC$B_TYPE Constant 255. 

XTCC$B_SUBTYPE Constant DECW$C_DYN_XTCC (1). 
XTCC$L_FLAGS See the following list. 
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Table 3—5 (Cont.) XTCC Data Structure 


Field 


Use 


The following fields are defined within XTCC$L_FLAGS: 


XTCC$V_MODE 


XTCC$V_ACTIVE 
XTCC$V_DYING 


XTCC$V_INPUT_IN_PROG 
XTCC$V_OUTPUT_IN_PROG 
XTCC$V_MARK_FOR_CLOSE 


XTCC$V_ERR_STS_VALID 


XTCC$V_LRP_ON_INPUT 
XTCC$V_LRP_ON_OUTPUT 


XTCC$V_WAIT_ON_WRITE 


XTCC$V_IN_AST_IN_PROG 


XTCC$V_OUT_AST_IN_PROG 


XTCC$A_TCQ 
XTCC$A_TPB 
XTCC$L_ICI 


Type of transport connection. Possible values 
are: 


¢ DECW$K_XPORT_REMOTE_SERVER 
(0) 

* DECW$K_XPORT_REMOTE_CLIENT (1) 

¢ DECW$K_XPORT_LOCAL_SERVER (2) 

* DECW$K_XPORT_LOCAL_CLIENT (3) 


Connection has been established. 


Connection is aborting and no further 
operations should be allowed. 

Internal flag used by common transport to 
check usage consistency. 

Internal flag used by common transport to 
check usage consistency. 

Deferred close operation requested. Used 
privately by the common transport. 

lf 1, XTCC$L_ERR_STATUS field contains 
additional information about the cause of 
connection termination. 

If 1, specific transport is using large XTCBs for 
input operations, otherwise, small XTCBs. 

If 1, transport caller is using large XTCBs for 
output operations, otherwise, small XTCBs. 
If 1, common transport is stalling to wait for 
specific transport to empty the output work 
queue so that a write_user operation can be 
initiated. (Write synchronization flag.) 

If clear, the previous input notification AST 
has been delivered and no AST is in progress. 
This flag prevents EXQUOTA errors due to 
excess use of ASTs. 


Reserved for use by Digital. 


Address of XTCQ used by this connection. 
Address of XTPB specific to this connection. 
Internal connection identifier. Used to find the 
corresponding IXTCC. 
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Table 3-5 (Cont.) XTCC Data Structure 


Field 
XTCC$A_IW_QUEUE 


XTCC$A_IFS_QUEUE 
XTCC$A_IFL_QUEUE 
XTCC$A_OW_QUEUE 
XTCC$A_OFS_QUEUE 
XTCC$A_OFL_QUEUE 


XTCC$A_TCQ_FLAGS 
XTCC$L_IWQ_FLAG 


XTCC$L_IFSQ_FLAG 
XTCC$L_IFLQ_FLAG 
XTCC$L_OWQ_FLAG 
XTCC$L_OFSQ_FLAG 
XTCC$L_OFLQ_FLAG 


XTCC$Q_USER_RESERVED 
XTCC$L_ERR_STATUS 


XTCC$L_REM_USER_LEN 
XTCC$A_REM_USER 
XTCC$L_REM_NODE_LEN 
XTCC$A_REM_NODE 


XTCC$L_LCL_USER_LEN 
XTCC$A_LCL_USER 
XTCC$W_IN_IOSB 


Use 


Address of input work queue in the XTCQ. 
For clients this is the event work queue; for 
servers this is the request work queue. 


Address of the small XTCB input free queue in 
the XTCQ. 


Address of the large XTCB input free queue in 
the XTCQ. 


Address of the output work queue in the 
XTCQ. 


Address of the small XTCB output free queue 
in the XTCQ. 


Address of the large XTCB output free queue 
in the XTCQ. 


Address of the flags longword in the XTCQ. 


Bit position of the input work queue notification 
request flag in the flags longword in the XTCQ. 


Bit position of the small XTCB input free queue 
notification request flag. 


Bit position of the large XTCB input free queue 
notification request flag. 


Bit position of the output work queue 
notification request flag. 


Bit position of the small XTCB output free 
queue notification request flag. 


Bit position of the large XTCB output free 
queue notification request flag. 


Quadword reserved for use by transport caller. 


Additional condition code information in case 
of connection failure. 


Length of the string identifying the remote 
user. (Valid for server only.) 


Address of the string identifying the remote 
user. (Valid for server only.) 


Length of the string identifying the remote 
node. (Valid for server only.) 


Address of the string identifying the remote 
node. (Valid for server only.) 


Reserved for use by Digital. 

Reserved for use by Digital. 

IOSB used in the $SYNCH system service 
when waiting for input operations to complete. 


(continued on next page) 
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Table 3-5 (Cont.) XTCC Data Structure 


Field Use 

XTCC$W_ON_IOSB IOSB used in the $SYNCH system service 
when waiting for output operations to 
complete. 

XTCC$W_OW_IOSB lIOSB used in the $SYNCH system service 


when stalling the transport caller so that the 
output work queue can be emptied prior to a 
write_user operation. (Write synchronization 
operation.) 

XTCC$L_IN_WAIT_TICKS Zero minus the number of watchdog-timer 
ticks remaining before input operation times 
out. Negative-to-zero transition causes the 
timeout to occur. 

XTCC$L_OUT_WAIT_TICKS Zero minus the number of watchdog-timer 
ticks remaining before output operation times 
out. Negative-to-zero transition causes the 
timeout to occur. 


XTCB Data Structure 


The transport layer uses transport communication buffers (XTCBs) to 
pass data between the server or Xlib and the underlying transport. Each 
connection can have small and large sizes of XTCBs, and the sizes may 
be different for different connections. A connection’s XTCBs exist for the 
duration of the connection and are user-modifiable. 


The XTCB structure is shown in Figure 3-8. 
Figure 3-8 XTCB Data Structure 
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Table 3-6 shows the contents of the XTCB data structure. 


Table 3-6 XTCB Data Structure 


Field 


XTCB$L_RFLINK 
XTCB$L_RBLINK 
XTCB$W_SIZE 
XTCB$B_TYPE 
XTCB$B_SUBTYPE 


XTCB$W_IOSB 


XTCB$A_POINTER 
XTCB$L_LENGTH 
XTCB$T_DATA 


3.1.5 XTCQ Data Structure 


Use 


Forward, relative pointer to next XTCB in the queue. 
Backward, relative pointer to previous XTCB in the queue. 
Length of XTCB in bytes. 

Constant 255. 


Constant DECW$C_DYN_XTCB_SRP (3) or DECW$C_ 
DYN_XTCB_LRP (4). DECW$C_DYN_XTCB_SRP 
represents a small XTCB; DECW$C_DYN_XTCB_LRP 
represents a large XTCB. 


IOSB for use by specific transport when performing the 
requested I/O operation with this XTCB. 


Pointer to next unused byte in data area. 
Length, in bytes, of valid data in data area. 
Start of variable-length data area. 


The transport communication queue (XTCQ) data structure contains the 
six per-connection communication queues and their state information. The 
six per-connection communication queues, which are described in more 
detail in Section 3.2, are as follows: 


¢ Event Work Queue. Identified by the XTCQ$L_EW_RFLINK and 
XTCQ$L_EW_RBLINK fields in the XTCQ. 


¢ Event Free Queue (small and large). Identified by the XTCQ$L_ 
EFS_RFLINK, XTCQ$L_EFS_RBLINK, XTCQ$L_EFL_RFLINK, and 
XTCQ$L_EFL_RBLINK fields in the XTCQ. 


¢ Request Work Queue. Identified by the XTCQ$L_RW_RFLINK and 
XTCQ$L_RW_RBLINK fields in the XTCQ. 


¢ Request Free Queue (small and large). Identified by the XTCQ$L_ 
RFS_RFLINK, XTCQ$L_RFS_RBLINK, XTCQ$L_RFL_RFLINK, and 
XTCQ$L_RFL_RBLINK fields in the XTCQ. 


The XTCQ data structure exists during the lifetime of a connection and is 


user-modifiable. 


The XTCQ data structure is shown in Figure 3~9. 
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Figure 3-9 XTCQ Data Structure 
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Table 3—7 shows the contents of the XTCQ data structure. 


Table 3-7 XTCQ Data Structure 


Field 


XTCQ$L_EW_RFLINK 
XTCQ$L_EW_RBLINK 
XTCQ$L_EFS_RFLINK 
XTCQ$L_EFS_RBLINK 
XTCQ$L_EFL_RFLINK 
XTCQ$L_EFL_RBLINK 
XTCQ$L_RW_RFLINK 
XTCQ$L_RW_RBLINK 
XTCQ$L_RFS_RFLINK 


Use 


Event work queue relative queue header. 

Event work queue relative queue header. 

Small XTCB event free queue relative queue header. 
Small XTCB event free queue relative queue header. 
Large XTCB event free queue relative queue header. 
Large XTCB event free queue relative queue header. 
Request work queue relative queue header. 

Request work queue relative queue header. 

Small XTCB request free queue relative queue 
header. 


(continued on next page) 
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Table 3-7 (Cont.) XTCQ Data Structure 


Field Use 

XTCQ$L_RFS_RBLINK Small XTCB request free queue relative queue 
header. 

XTCQ$L_RFL_RFLINK Large XTCB request free queue relative queue 
header. 

XTCQ$L_RFL_RBLINK Large XTCB request free queue relative queue 
header. 

XTCQ$L_FLAGS See the following list. 


The following fields are defined within XTCQ$L_FLAGS: 


XTCQ$V_EWQ_FLAG When 1, notification is desired when an XTCB is 
inserted on an empty event work queue. 
XTCQ$V_EFSQ_FLAG When 0, notification is desired when an XTCB is 
inserted on an empty small XTCB event free queue. 
XTCQ$V_EFLQ_FLAG When 0, notification is desired when an XTCB is 
inserted on an empty large XTCB event free queue. 
XTCQ$V_RWQ_FLAG When 1, notification is desired when an XTCB is 
inserted on an empty request work queue. 
XTCQ$V_RFSQ_FLAG When 0, notification is desired when an XTCB is 
inserted on an empty small XTCB request free queue. 
XTCQ$V_RFLQ_FLAG When 0, notification is desired when an XTCB is 
inserted on an empty large XTCB request free queue. 
XTCQ$V_ABORT_FLAG Reserved for use by Digital. . 


3.1.6 XTDB Data Structure 


The transport descriptor block (XTDB) data structure describes each 
attached transport. The XTDB keeps track of resources required by 
transport-specific functions, such as the known-object mailbox channel 
in the case of a DECnet server, and objects that will be cloned on a 
per-connection basis, such as the transport-specific XTFT function table. 


The XTDB structure exists during the lifetime of a transport. The XTDB 
structure is allocated from memory pages that have user-mode read 
access/executive-mode write access (UREW). The common transport layer 
maintains a queue of all XTDBs. 


The XTDB data structure is shown in Figure 3-10. 
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Figure 3-10 XTDB Data Structure 
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Table 3-8 shows the contents of the XTDB data structure. 


Table 3-8 XTDB Data Structure 


Field 


XTDB$A_FLINK 
XTDB$A_BLINK 


XTDB$W_SIZE 
XTDB$B_TYPE 
XTDB$B_SUBTYPE 
XTDB$L_FLAGS 


Use 


Forward, absolute pointer to next XTDB in queue. 


Backward, absolute pointer to previous XTDB in 
queue. 


Length of XTDB in bytes. 

Constant 255. 

Constant DECW$C_DYN_XTDB (5). 
See the following list. 


The following fields are defined within XTDB$L_FLAGS: 


XTPB$V_MODE 


XTDB$V_ACTIVE 


XTDB$V_DYING 


XTDB$A_TPB 
XTDB$L_REF_COUNT 


XTDB$Q_RESERVED 
XTDB$L_DEC_RESERVED 
XTDB$A_ITCC_FLINK 


XTDB$A_ITCC_BLINK 


XTDB$A_CONNECT_ABORT 


XTDB$A_CONNECT_ 
REQUEST 


Type of transport connection. Possible values are: 


¢ DECW$K_XPORT_REMOTE_SERVER (0) 

¢ DECW$K_XPORT_REMOTE_CLIENT (1) 

« DECW$K_XPORT_LOCAL_SERVER (2) 

« DECW$K_XPORT_LOCAL_CLIENT (3) 
Specific transport image has been activated and is 
running. 


Specific transport is aborting and no further 
operations should be allowed. Connections using 
this transport will be disconnected. 


Address of the transport-specific XTPB. 


Number of connections using this transport. 
Should be equivalent to the number of IXTCCs 
enqueued on the IXTCC queue header. 


Quadword reserved for use by specific transport. 
Reserved for use by Digital. 


Absolute queue header for IXTCCs of connections 
using this transport. 
Absolute queue header for IXTCCs of connections 
using this transport. 


Address of either the server or Xlib connection 
abort notification AST routine. Called with one 
argument: the XTCC by reference. 


Address of the server’s connection request 
notification AST routine. Called with one argument: 
the XTCC by reference. 


(continued on next page) 
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Table 3-8 (Cont.) XTDB Data Structure 
Field Use 


XTDB$L_FAMILY_NAME_LEN Length of the transport name string. 


XTDB$T_FAMILY_NAME Contains the transport family name string 
(for example, “DECNET” or “TCPIP”). The 
maximum size of the family name is 16 bytes, 
as determined by the constant XTDB$S_FAMILY_ 
NAME. XTDB$S_FAMILY_NAME is defined in 
DECW$EXAMPLES:XPORTEXAMPLEDEF.R32. 

XTDB$A_XPORT_TABLE Address of the XTFT structure for the specific 
transport. Returned as a value of the 
DECW$TRANSPORT_INIT routine, which is 
provided as a global name in every transport- 
specific image. 


XTFT Data Structure 


Each specific transport shareable image provides a set of transport-specific 
routines that are used for all connections using that transport. The 
transport function table (XTFT) data structure contains the addresses of 
these routines. During a transport attach operation, the transport-specific 
DECW$TRANSPORT_INIT routine initializes and returns that transport’s 
XTFT. 


The XTFT data structure exists during the lifetime of a specific transport 
and is accessible by the common transport. The XTFT data structure is 
shown in Figure 3—11. 


Figure 3-11 XTFT Data Structure 
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Figure 3-11 (Cont.) XTFT Data Structure 
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Table 3—9 shows the contents of the XTFT data structure. 


Table 3-9 XTFT Data Structure 


Field 
XTFT$L_REQUIREDO 


XTFT$L_RESERVEDO 


XTFT$A_EXECUTE_WRITE 
XTFT$A_WRITE 
XTFT$A_WRITE_USER 
XTFT$A_EXECUTE_FREE 
XTFT$A_FREE_INPUT_BUFFER 
XTFT$A_CLOSE 
XTFT$A_OPEN 
XTFT$A_ATTACH_TRANSPORT 
XTFT$A_RUNDOWN 
XTFT$L_XTCC_LENGTH 


XTFT$L_XTPB_LENGTH 


XTFT$L_XTDB_LENGTH 


Use 


Longword that must contain the value 
XTFT$K_REQUIREDO (—1515870811 
decimal). 


Longword reserved for use by a specific 
transport. 


Address of execute-write routine. 
Address of write routine. 
Address of write-user routine. 
Address of execute-free routine. 
Address of free-input routine. 
Address of close routine. 
Address of open routine. 
Address of attach routine. 
Address of rundown routine. 


Length, in bytes, of XTCCs used by this 
transport. Must be at least XTCC$W_SIZE. 


Length, in bytes, of XTPBs used by this 
transport. Must be at least XTPBSW_SIZE. 


Length, in bytes, of XTDBs used by this 
transport. Must be at least XTDBSW_SIZE. 





(continued on next page) 
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Table 3—9 (Cont.) XTFT Data Structure 





Field Use 

XTFT$L_IXTCC_LENGTH Length, in bytes, of IXTCCs used by this 
transport. Must be at least IXTCC$W_ 
SIZE. 

XTFT$L_REQUIRED1 Longword that must contain the value 
XTFT$K_REQUIRED1 (-1768515946 
decimal). 

3.2 Transport Layer Communication Queues 
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When a connection is created, a specific transport calls the 
DECW$XPORT_ALLOC_INIT_QUEUES routine to create six 
communication queues that pass XTCBs between servers and clients 
and between transport-common and transport-specific components. The 
communication queues are relative queues as used by the VAX REMQxI 
and INSQxI instructions. With the exception of the local transport, the 
queues are private to one side of the connection. 


The communication queue headers are stored in the XTCQ data structure. 
Each queue is named according to its function, as shown in Table 3-10. 


A queue element (XTCB) must be removed from its queue before its 
contents can be modified by either the server or Xlib or by transport layer 
internal functions. 


The component that adds XTCBs to a queue is called the producer; the 
component that removes XTCBs from a queue is called the consumer. 


Table 3-10 Transport Layer Communication Queues 


Queue Name Function 

EventWorkQueue Queue of XTCBs containing events, errors, 
and replies to be sent to Xlib 

EventFreeQueue Return queue for processed XTCBs from the 

large and small EventWorkQueue 

RequestWorkQueue Queue of XTCBs containing requests to be 
sent to a server 

RequestFreeQueue Return queue for processed XTCBs from the 

large and small RequestWorkQueue 


The transport layer communication queues are shown in Figure 3-12. For 
the purpose of simplicity, Figure 3-12 combines the free queues; there are 
actually separate free queues for large and small XTCBs. 
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Figure 3-12 Transport Layer Communication Queues 
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You can consider the buffers in the transport layer communication queues 
to be in an infinite loop similar to a ski lift; once a buffer is received at one 
end of the connection it is emptied and added to the returning loop. 


The transport layer further distinguishes between the queues so that 
terminology is consistent on both sides of the client/server connection; 
when the term “input” is used in the context of a client, it means 
“event.” Conversely, “input” in the context of the server means “request.” 
Table 3-11 shows the delineation of the queues. 


Table 3-11 Views for the Client/Server Communication Queue 





General Queue Name Client View Server View 
EventWorkQueue InputWorkQueue OutputWorkQueue 
EventFreeQueue InputFreeQueue OutputFreeQueue 
RequestWorkQueue OutputWorkQueue InputWorkQueue 
RequestFreeQueue OutputFreeQueue InputFreeQueue 





Figure 3-13 shows the result of adding the client/server views to the model 
of the queues shown in Figure 3-12. 
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Figure 3-13 Client/Server Communication Queue Views 
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In the case of local communication where the client and server are 
executing on the same hardware, the queues are shared between the 
client and server. Each queue has two meanings depending upon 
whether a server or a client is looking at the queue. For example, the 
EventWorkQueue is simultaneously the client’s InputWorkQueue and the 
server’s OutputWorkQueue. 


3.2.1. Transport Common/Specific Queue Relationship 
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The transport layer seems to be a single entity that somehow moves data 
across the wire, but there are actually two transport layers involved: a 
transport layer on the client side and a transport layer on the server side. 
Each side of the client/server connection initializes the common transport 
and attaches one or more specific transports. Each transport layer builds 
and maintains its own set of connection queues; the queues are private 
to each side of the wire and are not actually shared across a network 
connection. The local transport is an exception; the queues are built in 
shared global sections. 


General discussions of the relationship between the transport layer and 
other DECwindows components commonly treat the transport layer as 
a single entity that exists on both sides of the client/server connection. 
However, the transport layer consists of the transport-common and 
transport-specific components. 


Transport Layer Architecture 
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The transport-common and transport-specific components pass data to 
each other by means of a queue implementation that is similar to the 
queues employed between Xlib and the transport-common code. This 
intratransport queuing implementation is shown in Figure 3-14. 


Figure 3-14 Transport Common/Specific Connection 
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3.2.2 Adding and Removing Buffers from the Queues 
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The server and Xlib call transport-common routines such as 
DECW$XPORT_READ, DECW$XPORT_FREE_INPUT_BUFFER, 
GET_OUTPUT_BUFFER, and DECW$XPORT_CHAINED_WRITE to 
remove or add buffers from the queues, as described in Section 3.3.1.6 and 
Section 3.3.1.7. 


Some of the transport-common routines may call transport-specific 
routines such as XTFT$A_WRITE to actually get the buffer from the 
queue. Other transport-common routines such as DECW$XPORT_READ 
operate only in the common layer and communicate with the specific 
transport only by manipulating data structures. 


An example of the transport-common/transport-specific queue process is as 
follows: 


1 Xlib calls the DECW$XPORT_GET_OUTPUT_BUFFER routine to 
get a free XTCB. DECW$XPORT_GET_OUTPUT_BUFFER removes 
(REMQHI) an XTCB from the OutputFreeQueue. 


2 Xlib copies data to the XTCB and calls DECW$XPORT_CHAINED_ 
WRITE. 


3 DECW$XPORT_CHAINED_WRITE inserts (INSQTI) the XTCB on 
the OutputWorkQueue. If the queue was empty, the XTFT$A_WRITE 
routine is called to determine if an I/O should be initiated. 


4 When the write completes, the XTCB is inserted on the tail of the 
OutputFreeQueue. Xlib is then notified if it is waiting for an output 
buffer. If the OutputWorkQueue is not empty, another I/O is initiated. 


Figure 3-15 adds the transport-common/transport-specific queue process 
to Figure 3-14. 
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Figure 3-15 Transport Common/Specific Queues 
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On the server side of the connection, the underlying transport notifies 
the transport-specific layer that data is available. For example, DECnet 
delivers this notification in the form of a $QIO read completion for the 
connection; that is, the specific transport receives a read-completion AST 
in response to a $QIO read for a given connection. 


When the specific transport receives a read completion, it performs the 
following steps: 


1 Inserts (INSQTI) the XTCB that now has data in it on the 
InputWorkQueue. 


2 If input notification is requested, it sends the server an input-notify 
AST to indicate that an XTCB is available for the connection. 


3 Removes (REMQHI) an XTCB from the InputFreeQueue. 
4 Initiates a new read into the XTCB. 


The server calls DECW$XPORT_READ to remove (REMQHI) the XTCB 
from the InputWorkQueue. When the dispatcher is finished with the 
XTCB, it calls DECW$XPORT_FREE_INPUT_BUFFER to insert the 
XTCB on the InputFreeQueue, and the queue cycle is complete. 


If the InputFreeQueue is empty and input for the connection is enabled 
when DECW$XPORT_FREE_INPUT_BUFFER inserts the XTCB, 
DECW$XPORT_FREE_INPUT_BUFFER calls XTFT$A_EXECUTE_FREE 
to remove (REMQHI) the XTCB it just placed on the InputFreeQueue. In 
the case of DECnet or TCP/IP, the XTCB is then used to store the result of 
the next QIO read operation for the connection. 


3.2.3 Communication Queue Notification Flags 
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It is possible that at any given time all of a connection’s input or output 
XTCBs will be in use. To provide for this possibility, there is a flag 
associated with each queue that tracks the state of the queue. When a 
queue has been exhausted, the component that is removing XTCBs from 
the queue (the consumer) sets the state flag to indicate that it wants to be 
notified when an XTCB becomes available. 


If the component that is adding XTCBs to the queue (the producer) notices 
that the queue was empty, it tests the state flag and, if set, notifies the 
consumer that an XTCB is available. 


The notification is context dependent. When the consumer is a transport- 
specific layer, as described in Section 3.2.1, the notification causes I/O to 
be initiated using the recently inserted queue element. 


When the consumer is the transport-common layer, notification consists of 
delivering an AST or setting an event flag. For example, the transport- 
specific code on the server side of the connection sends the transport- 
common layer an AST to say that input is available for a connection. 
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The notification flags are shown in Table 3-12. 


Table 3-12 Communication Queue Notification Flags 


Fiag Name Meaning 

EventWorkQueueFlag Event consumer awaits event XTCBs 
EventFreeQueueFlag Event producer awaits returned event XTCBs 
RequestWorkQueueFlag Request consumer awaits request XTCBs 
RequestFreeQueueFlag Request producer awaits returned request XTCBs 


As in the case of the local communication queues, each interest flag 

in a local connection has two meanings depending upon whether a 
server or a client is looking at the queue: the EventWorkQueue is 

the client’s InputWorkQueue and the server’s OutputWorkQueue; the 
RequestFreeQueuelnterest bit is the client’s OutputFreeQueuelnterest bit 
and the server’s InputFreeQueuelnterest bit. 


A queue element consumer functions as follows: 
1 Sets the queue notification flag (in case the queue is empty). 
2 Removes an element from the queue— 


e Ifthe queue is empty, the consumer can wait for notification that 
data is available or it can return without the buffer. 


e Ifthe queue is not empty, the consumer clears the notification flag 
and returns with the buffer. 


A queue element producer functions as follows: 
1 Inserts an element on the queue. 


2 Ifthe queue was empty and the queue flag was set, clears the queue 
flag and generates a notification to tell the consumer that data is 
available. 


3.2.4 Preventing Queue Access Conflict 


The transport layer uses interlocked queues to synchronize access between 
the queue producer and consumer. Server or Xlib attempts to remove and 
insert buffers result in the interlocked instructions being used in user 
mode, possibly at AST level. 


The queues are also accessed by inner-mode routines using the example_ 
queue emulations found in DECW$EXAMPLES:XPORT_EXAMPLE_ 
QUEUE. Executive-mode code cannot use the REMQxI and INSQxI built- 
ins to access a relative queue that is modifiable by user-mode code because 
of the possibility of overwriting user-write-protected memory. 


The XPORT_EXAMPLE_QUEUE.MAR module provides emulations of 
the REMQxI and INSQxI instructions that perform appropriate probing. 
The REMQxI and INSQxI emulations use the VAX PROBEW instruction 
to probe the memory occupied by a queue entry to determine if it has 
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3.2.4.1 


user-mode write access and return an ACCVIO status if the memory is not 
accessible. 


The REMQxI and INSQxI emulations also perform a spin-and-wait to see 
if the queue is locked by another transport user. 


Special-Case Queue Conditions 
There are two special-case queue conditions: 


e As described in Section 3.2.3, the queue consumer sets the notification 
(notify-if-empty) queue flag before attempting a REMQHI from the 
queue. If the queue is not empty, the consumer removes the queue 
element and clears the flag. 


The producer checks this flag after adding an element to the queue. 
If the producer is able to insert a queue element between the time 
when the consumer sets and clears the flag, the producer generates 
an input-available notification when none is necessary. This is called 
spurious notification, and queue consumers must be prepared for it. 


e A second condition occurs when the consumer can preempt the 
producer thread, such as the output half of a remote transport. 


For example, assume that the producer does an INSQTI of some 
element on the queue and is about to test the queue flag. However, 
before the producer can test the queue flag, the consumer does the 
following: 


1 Removes (REMQHI) an XTCB and processes it 
2 Fails when it attempts to remove another XTCB 
3 Sets the queue interest flag and quits 


The producer does not know that the queue is now empty; it continues 
to run and attempts to notify the consumer. In this case, however, 
notification consists of removing the head queue element and issuing 
a transport write operation from data in the queue element. Because 
the element is no longer on the queue, the notification procedure must 
be prepared to handle the empty queue. 


3.3 Transport-Common and Transport-Specific Components 
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As described in Section 1.2, the transport layer is separated into transport- 
common and transport-specific functions. The routines that support the 
transport-common functions have names of the form DECW$XPORT_xxx 
and provide the generic services needed by Xlib or the server. 


Some transport-common routines only select and call the correct transport- 
specific routine. Other transport-common routines perform substantial 
processing prior or subsequent to invoking the associated transport-specific 
routine. 


A special set of utility routines and macro definitions perform thread 
suspension and resumption, global section mapping and maintenance, 
queue maintenance, and communication between transport layer 
components for use by transport layer developers. See Chapter 7 for 
more information. 
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The transport-common routines call transport-specific routines that are 
private to a particular transport service, such as DECnet. The addresses 
of the transport-specific routines are contained in the XTFT data structure 
and, along with VMS packaging requirements, comprise the interface to 
which a transport developer must program. 


3.3.1. Transport-Common Functions 


3.3.1.1 


The transport-common code performs the following functions: 

¢ Initializes the transport-specific layer 

e Attaches the transport-specific layer 

¢ Opens a connection 

¢ Gets and sets transport-common and per-connection attributes 
e Allocates memory 

e Reads from the input queue 

¢ Writes to the output queue 


¢ Closes a connection 


Subsequent sections describe the transport-common functions. 


Initializing the Transport-Common Layer 

The DECW$XPORT_INITIALIZE routine is called before any other 
DECwindows transport-common routine. Xlib and the server call the 
DECW$XPORT_INITIALIZE routine to initialize the transport-common 
code. The common transport knows whether it was called by Xlib or 
the server by a caller_type argument that identifies the caller as a 
client (DECW$K_XPORT_CLIENT) or as the server (DECW$K_XPORT_ 
SERVER). 


DECW$XPORT_INITIALIZE initializes the global XTPB data structure, 
from which other XTPB data structures inherit their default values. (See 
Section 3.1.1.) 

Transports and connections that are subsequently attached or opened 
inherit the parameters set at initialization time unless they override 
them in an itmlst argument to the DECW$XPORT_INITIALIZE or 
DECW$XPORT_ATTACH_TRANSPORT routines. Both Xlib and the 
server override some of these defaults. 


The DECW$XPORT_INITIALIZE routine calls the DECW$XPORT_SET_ 
ATTRIBUTES routine to load the global XTPB data structure with the 
attributes passed in the itmlst argument. 


The itmlst argument can specify the following parameters: 


¢ The address of a procedure to call when an input operation is 
completed on the connection and input notification has been enabled 


e The address of a procedure to call when an output operation is 
completed on the connection and output notification has been enabled 
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¢ The size of the data area of the large communication buffers used by 
transport | 


e The size of the data area of the small communication buffers used by 
transport 

¢ A value to be passed to the input notification routine 

e A value to be passed to the output notification routine 

e¢ The number of the event flag to be set for input notification 

e The number of the event flag to be set for output notification 


¢ The number of seconds the default waiting procedures are allowed to 
wait for output completion 


¢ The number of seconds the default waiting procedures are allowed to 
wait for input completion 


Attaching a Transport-Specific Layer 

On the client side of the connection, Xlib calls DECW$XPORT_ATTACH_ 
TRANSPORT to attach and initialize only those transports to which it 
wants to connect. Xlib determines the transports to attach and initialize 
as follows: 


e Ifthe call to the Xlib OPEN DISPLAY routine specifies a display name, 
Xlib parses the display name to determine the transport to initialize. 


e Ifthe call to the Xlib OPEN DISPLAY routine specifies a null display 
name, Xlib uses the result of the last SET DISPLAY command to 
determine the transport to initialize. 


On the server side of the connection, the server must tell the common 
transport which specific transports to attach and initialize. The 
server uses the logical name DECW$SERVER_TRANSPORTS (see 
SYS$MANAGER:DECW$PRIVATE_SERVER_SETUP.TEMPLATE) to 
accomplish this. 


For example, DECW$SERVER_TRANSPORTS could translate to 
“DECNET,LOCAL,TCPIP”. The server calls the common transport 
DECW$XPORT_ATTACH_TRANSPORT routine for each transport 
identified by the logical name. The transport_name argument specifies 
the transport, such as “DECNET”. 


DECW$XPORT_ATTACH_TRANSPORT needs a way to associate the 
transport name specified in the transport_name argument with a 
specific transport’s image. When called by either Xlib or the server, 
DECW$XPORT_ATTACH_TRANSPORT attempts to locate and activate 
an image with a name in the form SYS$SHARE:DECW$TRANSPORT_ 
transport_name.EXE. If it does not find one, DECW$XPORT_ATTACH_ 
TRANSPORT looks for a name in the form SYS$SHARE:DECW_ 
TRANSPORT_transport_name.EXE. 


For example, if DECW$XPORT_ATTACH_TRANSPORT could not find an 
image with the name SYS$SHARE:DECW$TRANSPORT_FOO.EXE, it 
would look for SYS$SSHARE:DECW_TRANSPORT_FOO.EXE. 


3.3.1.3 


Note: 
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Transport names that contain a dollar sign ($) character, such 
as SYS$SSHARE:DECW$TRANSPORT_DECNET, are reserved for 
transport images supplied by Digital. 


Transport names that do not contain a “$” character 
are reserved for third-party and customer transport 
images. These transport names must be in the form 
SYS$SHARE:DECW_TRANSPORT_transport_name.EXE. 


If the image activation is successful, DECW$XPORT_ATTACH_ 
TRANSPORT builds an XTDB, initializes the common fields, and calls 

the transport-specific DECW$TRANSPORT_INIT routine to complete the 
initialization by initializing the XTFT data structure with the addresses of 
the transport-specific routines. 


Every transport-specific image (SYS$SHARE:DECW$TRANSPORT_ 
transport_name.EXE or SYS$SHARE:DECW_TRANSPORT_transport_ 
name.EXE) must provide an implementation of DECW$TRANSPORT_ 
INIT for its initialization routine. A transfer vector to the 
DECW$TRANSPORT_INIT routine must be placed in the first image 
section of the transport-specific image. 


The DECW$XPORT_ATTACH_TRANSPORT routine performs the 
following functions: 


¢ Validates the transport_name argument. 

¢ Checks to see if the transport-specific image is already attached. 
¢ Builds the transport-specific image file name. 

e Activates the transport-specific image. 


¢ Calls the transport-specific DECW$TRANSPORT_INIT initialization 
routine to get the address of the XTFT. 


e¢ Allocates memory for XTDB and XTPB. Copies the contents of the 
global XTPB to the new XTPB. 


e Attaches the XTPB to the XTDB and sets the XTDB attributes from 
the itmlst argument. 


e Fills in the XTDB contents, such as the transport family name. 
e Enqueues the XTDB on the global XTDB queue. 


¢ Calls the transport-specific attach routine, XTFT$A_ATTACH_ 
TRANSPORT, and returns the status. 


Opening a Connection 

Xlib clients call the Xlib OPEN DISPLAY routine to establish a 
connection with a server. Xlib in turn calls the DECW$XPORT_ATTACH_ 
TRANSPORT and DECW$XPORT_OPEN routines. 


The DECW$XPORT_OPEN routine performs the following functions: 


e Tries to find a transport that will initiate a connection. 
DECW$XPORT_OPEN searches the global XTDB queue for a 
transport whose family name matches the xportnam argument. 
xportnam is typically the transport specified in the last use of the 
SET DISPLAY command (for example, “DECNET”). 
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¢ Copies the attached transport parameters to connection-specific 
parameters. Allocates IXTCC and XTPB data structures for the 
connection and partially establishes the connection context. 


e Updates the connection parameters if an itmlst argument was 


specified. 


e Calls the transport-specific open routine, XTFT$A_OPEN, to try to 


open the connection. 


3.3.1.4 Getting and Setting Transport Attributes 


The DECW$XPORT_SET_ATTRIBUTES and DECW$XPORT_GET_ 
ATTRIBUTES routines get and set XTPB and XTCC attributes associated 
with a connection-specific XTPB or the global XTPB. (It is not possible to 
specify the transport-specific XTPB.) When the XTCC argument specifies 
an active connection, the parameters of that connection are modified or 
returned; when XTCC is zero, the global parameters are modified or 


returned. 


DECW$XPORT_SET_ATTRIBUTES performs some checks to detect 


invalid combinations of parameters. 


3.3.1.5 Allocating Transport Memory 


The common transport uses the routines described in Table 3-13 to 


allocate and deallocate memory. 


Note: The VMS Run-Time Library memory allocation routines may not 


be used from inner access modes. 


Table 3-13 Transport Memory Allocation Routines 


Routine Name Description 
DECW$XPORT_ALLOC_INIT_ Allocates storage for an XTCC, XTCQ, and 
QUEUES all of the XTCBs for a connection. These 


structures are user-writable. Places all of the 
XTCBs on the appropriate free queues. 

DECW$XPORT_ALLOC_PMEM Allocation routine for protected (user-readable, 
executive-writable) structures. Allocates a block 
of storage of a given size. 

DECW$XPORT_DEALLOC_PMEM Memory deallocation routine (companion to 
DECW$XPORT_ALLOC_PMEM). Deallocates 
previously allocated structure. 


DECW$XPORT_DEALLOC_ Deallocates a block of storage previously 
QUEUES allocated for the queues of a connection. 
3.3.1.6 Common Transport Read Routines 


The common transport performs a read operation to remove an input 
XTCB or return an input XTCB to the queue. There are two read routines: 
DECW$$XPORT_FREE_INPUT and DECW$XPORT_READ. The read 


routines are described in Table 3-14. 
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Table 3-14 Transport Read Routines 


Routine Name 


DECW$$XPORT_FREE_INPUT 


DECW$XPORT_READ 


Writing to the Transport 


Description 


Returns an XTCB aquired with DECW$XPORT_ 
READ to the input free queues. If no XTCB 
was on the queue and notification is desired, 
DECW$$XPORT_FREE_INPUT removes the 
XTCB and initiates a read operation on the 
connection; that is, it calls the transport-specific 
XTFT$A_FREE_INPUT_BUFFER routine, which 
in turn does a read operation for the underlying 
transport. 


Attempts to remove an XTCB from the head of 
the input work queue. If the attempt succeeds, 
the address of the XTCB is returned to the 
caller and it returns with successful status. 

lf DECWS$XPORT_READ fails, one of the 
following actions occurs: 


¢ — If it fails and is a nonblocking operation, 
input notification is enabled and it returns 
failed status. 

¢ If it fails and is a blocking operation, the call 
uses a $SYNCH system service call to wait 
for an input buffer to become available. 


The common transport includes routines to write data from the user’s 
environment to a connection. The transport-common routines in turn call 
transport-specific routines to send the data across the wire. 


The common transport write routines are described in Table 3-15. 


Table 3-15 Common Transport Write Routines 


Name 


DECW$XPORT_GET_OUTPUT_ 
BUFFER 


Description 


Gets an XTCB from the output free queue. The 
mode argument modifies the operation: 


e lf the no-block bit is set and no XTCB is 
available when the call is made, the routine 
returns a buffer-not-available status and 
output notification is enabled. 

¢ — If the no-block bit is clear, a call to SSYNCH 
is made to wait for a buffer to become 
available. If timeouts are enabled, it is 
possible for the $SYNCH call to time out. 


The data-length argument provides a hint as to 
what size buffer the caller should receive. 


(continued on next page) 
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Table 3-15 (Cont.) Common Transport Write Routines 


Name Description 


DECW$XPORT_WRITE Initiates a writing operation on the connection 
associated with an XTCC. The DECW$XPORT_ 
WRITE routine copies the data from a 
buffer provided by the user to XTCBs. 
DECW$XPORT_WRITE supports both blocking 
and nonblocking modes. 


DECWS$XPORT_WRITE may perform multiple 
callback operations to the user’s callback 

routine, specified by the copy_rtnadr argument, 
to get data copied from the caller’s environment 
into the XTCBs. 


copy_rtnadr is called with the address of an 

XTCB as an argument and the user-specified 
copy_rtnarg argument. The transport user is 
expected to partially fill the XTCB and return 

with the status of the write request. 


Works similarly to DECW$XPORT_COPY_ 
AND_WRITE but allows the caller to copy data 
from noncontiguous structures or compute the 
data dynamically when that is more practical. 


DECW$XPORT_COPY_AND__ Initiates a writing operation on the connection 

WRITE associated with the XTCC. DECW$XPORT_ 
COPY_AND_WRITE performs a buffered write 
operation and returns the size of the data 
actually copied in the retbuflen argument. 


DECW$XPORT_CHAINED_WRITE Initiates a writing operation on the connection 
associated with the XTCC. The itmlst argument 
specifies a number of buffers to be written 
to the connection. Two types of buffers are 
supported: XTCBs and user buffers. If the 
specific transport being used does not support 
writing from the user’s buffer, DECW$XPORT_ 
CHAINED_WRITE performs a copy operation 
using DECW$XPORT_COPY_AND_WRITE. 


3.3.1.8 Transport Layer Timer Mechanism 
The transport layer timer mechanism is used to create an inner-mode 
AST at 5-second intervals so that the transport-common layer can search 
through the transport descriptors and connection contexts to find work 
that needs to be done. This timer mechanism is particularly useful 
in generating timeouts for $SYNCH operations, such as XPORT_IN_ 
NOTIFY_WAIT, that have gone on too long. 


When the time period expires, the timer finds connections that have been 
waiting for the number of ticks specified in the connection’s XTPB. The 
wait operations are completed by assigning a SS$_TIMEOUT status to the 
appropriate I/O status block (IOSB), setting an event flag, and setting the 
XTCC$V_DYING bit in the XTCC. 


3.3.1.9 
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Closing a Connection 

A transport connection is closed in response to a call to the Xlib CLOSE 
DISPLAY routine, or the server closing the connection. The XTCC data 
structure XTCC$V_DYING field is set when the connection is to be closed. 


The DECW$XPORT_CLOSE routine terminates a connection and releases 
the resources that are associated with the connection. The server and Xlib 
are expected to return any XTCBs acquired through DECW$XPORT_ 
READ and DECW$XPORT_GET_OUTPUT_BUFFER before calling 
DECW$XPORT_CLOSE. After calling DECW$XPORT_CLOSE, the 
structures used by the connection (XTCC, XTCQ, IXTCC, XTPB, and 
XTCBs) must not be referenced. 


The DECW$XPORT_CLOSE routine calls the transport-specific connection 
close routine to actually break the network link. 


3.3.2 Transport-Specific Functions 


3.3.2.1 


The transport-specific code performs the following functions: 

¢ Initializes and returns the address of the XTFT 

¢ Initializes (attaches) a specific transport 

e Connects a client to a server by means of the chosen transport 
¢ Writes data from XTCBs to the transport 

¢ Reads data into XTCBs from the transport 

e Closes a connection and releases connection structures 


e Initiates image rundown processing for the connection 
Subsequent sections describe the transport-specific functions. 


Initializing the Transport 

The XTFT data structure contains the addresses of the transport-specific 
routines. The common transport must therefore always be able to find 
the transport-specific XTFT structures. To make sure that the common 
transport can find the XTFT structures, every transport-specific image 
must provide a routine, DECW$TRANSPORT_INIT, as the initialization 
routine of that image. 


A transfer vector to the DECW$TRANSPORT_INIT routine must be 
provided in the first image section of the transport-specific image. See 
Section 8.3.19 for an example of this transfer vector. 


The DECW$XPORT_ATTACH_TRANSPORT routine calls the 
DECW$TRANSPORT_INIT routine to initialize and return the XTFT. 
Once the XTFT is initialized, DECW$XPORT_ATTACH_TRANSPORT 
calls the XTFT$A_ATTACH_TRANSPORT routine found in this data 
structure to complete the transport-specific initialization. 
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3.3.3 Attaching the Specific Transport 


As described in Section 3.3.2.1, the DECW$XPORT_ATTACH_ 
TRANSPORT routine calls the XTFT$A_ATTACH_TRANSPORT routine 
to complete the transport-specific initialization. 


XTFT$A_ATTACH_TRANSPORT functions differently depending on 
whether the server or Xlib called it. If Xlib called it, XTFT$A_ATTACH_ 
TRANSPORT performs relatively little transport-specific initialization. 


If the server called it, XTFT$A_ATTACH_TRANSPORT performs 
additional transport-specific initialization. For example, for DECnet, 
XTFT$A_ATTACH_ TRANSPORT might function as follows: 


¢ Create a mailbox 


e Assign a channel to the network device and associate the mailbox with | 
this channel 


e Associate an object name (for example, X$X0) to which clients may 
refer with the network channel 


¢ Issue a $QIO read to the mailbox to receive notification of connection 
attempts by clients 


The TRANSPORT_READ_QUEUE and TRANSPORT_READ_AST 

routines in the example transport are called to initiate a read on the | 
transport channel. TRANSPORT_READ_QUEJUE is called by XTFT$A_ 
ATTACH_TRANSPORT to perform the first $QIO read on the newly 
attached connection. The XTFT$A_ATTACH_TRANSPORT routine assigns 
a network channel for the transport and then calls TRANSPORT_READ_ 
QUEUE to listen on the channel for a connection attempt from a client. 


TRANSPORT_READ_AST is a sample read-completion AST routine for 
the transport’s network channel. 


3.3.3.1 Opening a Connection 
The XTFT$A_OPEN routine tries to connect a client to a server. 


The transport-common DECW$XPORT_OPEN routine attempts to locate 
a transport with a name matching the one passed in the xportnam 
argument (for example, “DECNET”). If a matching transport is found, the 
XTFT$A_OPEN routine is called with the server number and workstation 
node name arguments, and an IXTCC and XTPB that have been partially 
initialized. (Xlib calls DECW$XPORT_OPEN with an item list that gives 
its desired defaults. ) 


XTFT$A_OPEN is responsible for the allocation and initialization of the 
XTCC, XTCQ, and all necessary XTCBs, and starting an initial read if 
needed. Parameters that would affect these operations are found in the 
XTPB attached to the IXTCC by means of the IXTCC$A_TPB field. 


3.3.3.2 


3.3.3.3 
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Writing XTCBs to a Transport 
There are three transport-specific routines that are called through the 
XTFT data structure for writing to the transport: 


e XTFT$A_EXECUTE_WRITE 
¢ XTFT$A_WRITE 
¢ XTFT$A_WRITE_USER 


Many transport-specific images will also need a write-completion routine. 
A sample write-completion AST routine, WRITE_AST, is shown in 
Chapter 8. 


The transport-specific write routines are described in Table 3-16. 


Table 3-16 Transport-Specific Write Routines 


Routine Description 





XTFT$A_EXECUTE_WRITE Writes the contents of an XTCB to a connection. 
XTFT$A_EXECUTE_WRITE is called when the 
common transport inserts an XTCB on an empty 
output work queue. XTFT$A_EXECUTE_WRITE 
must decide whether to call DECW$$XPORT_WRITE 
so that an I/O operation can be started in executive 
mode. 


XTFT$A_WRITE Attempts to write an XTCB to the connection 
associated with the XTCC. XTFT$A_WRITE writes the 
contents of XTCBs across the wire. If there is nothing 
to write, that is, the XTCBs are empty, XTFT$A_ 
WRITE inserts the XTCBs on the appropriate (small 
or large) output free queue. This is a method of 
populating the free queues. 


If the write operation fails, XTFTGA_WRITE puts the 


XTCB back at the head of the output work queue and 
sets the connection status to dying. 


XTFT$A_WRITE_USER Attempts to write a buffer in the user’s address space 
to a transport connection. XTFT$A_WRITE_USER 
can use the common routine DECW$XPORT_COPY_ 
AND_WRITE to copy the user’s buffer into XTCBs 
and queue them for writing, or wait for the output work 
queue to empty and issue $QIOs directly from the 
user’s buffer. 


Reading XTCBs from a Transport 

There are two transport-specific routines that are called through the XTFT 
data structure for reading from the transport: XTFT$A_EXECUTE_FREE 
and XTFT$A_FREE_INPUT_BUFFER. 


Many transport-specific images will also need a read-completion routine. 
A sample read-completion AST routine, FREE_INPUT_AST, is shown in 
Chapter 8. 
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The transport-specific read routines are described in Table 3-17. 


Table 3-17 Transport-Specific Read Routines 


Routine Description 


XTFT$A_EXECUTE_FREE Returns an XTCB to a local connection. 
DECW$XPORT_EXECUTE_FREE calls XTFT$A_ 
EXECUTE_FREE to remove the buffer just placed 
on the input free queue. In the case of DECnet or 
TCP/IP, the buffer is then used to store the result of 
the next $QIO read operation for the connection. 


XTFT$A_FREE_INPUT_ In the case of DECnet or TCP/IP, XTFTS$A_FREE_ 

BUFFER INPUT_BUFFER does a $QIO read operation for a 
connection into the provided buffer. If there is nothing 
to read for the connection, XTFT$A_FREE_INPUT_ 
BUFFER inserts the XTCB on the free queue and 
sets the connection state to dying. 


3.3.3.4 Closing a Connection 
The connection close routines close a connection and release the structures 
associated with the connection. The common transport layer begins 
deallocation of all connection resources including, but not limited to, 
channels, XTCC, XTCBs, XTPB, and transport-private data. After this is 
done, the transport user must not refer to any structures associated with 
the connection. 


There are two transport-specific routines that work together to close a 
connection: XTFT$A_CLOSE and XTFT$A_RUNDOWN. XTFT$A_CLOSE 
uses an additional routine, CLOSE_AND_DEALLOCATE_AST, to clean up 
after aborted I/O operations. A sample CLOSE_AND_DEALLOCATE_AST 
routine is shown in Chapter 8. 


The transport-specific connection close routines are described in 
Table 3-18. 


Table 3-18 Transport-Specific Connection Close Routines 


Routine Description 
XTFT$A_CLOSE Marks the connection as dying and cancels and deassigns 


the channel to the connection. XTFT$A_CLOSE declares 
an AST to the CLOSE_AND_DEALLOCATE_AST routine 

that is executed after any completion ASTs. This performs 
the final cleanup operations such as structure invalidation 

and deallocation. 


XTFT$A_RUNDOWN Invoked by the common transport when the current image 
exits. Each specific transport must release any resources 
necessary for a clean exit. 


3.3.3.5 
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The Transport-Specific Callback 

When a specific transport receives a connection request, it completely 
sets up the new connection and then calls the server connection-request 
routine, identified by the XTDB$A_CONNECT_REQUEST field, to see 
if the server accepts the connection. The sample transport shown in 
Chapter 8 uses the TRANSPORT_READ_AST, TRANSPORT_READ_ 
QUEUE, and TRANSPORT_OPEN_CALLBACK routines to accomplish 
this task. 
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Transport Walk-Through 


Note: 


This chapter describes a walk-through of transport layer activities, 
including transport initialization, for both the server and Xlib. The walk- 
through gives an overview of the transport layer activities; it does not 
describe every step of the process. The walk-through is based on the 
sample TCP/IP transport. 


The boxed numbers in the illustrations correspond to the buffers, 
or XTCBs, that are being queued. 


The convention for TCP/IP is that server number 0 listens on port 
6000. Port 5000 is used in this example to prevent collision with a 
“real” TCP/IP transport. 
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Server Startup 
DECW$XPORT INITIALIZE 
Create global XTPB. 
DECW$XPORT_ATTACH_TRANSPORT 
XTFT$A_ATTACH_TRANSPORT 


Assign channel to UCX$DEVICE. 
Create TCP port 5000. 

Begin listening on port 5000. 

Assign channel to UCX$DEVICE. 

$QIO ACCEPT CHANNEL to port 5000. 


XOpenDisplay 


DECW$XPORT_ INITIALIZE 
Create global XTPB. 


DECW$XPORT_ATTACH_TRANSPORT 
XTFT$A_ATTACH_TRANSPORT 


DECW$XPORT_OPEN 
Allocate IXTCC and XTPB. 
XTFT$A_OPEN 
Allocate resources (XTCQ, 
XTCC, XTCBs). 
Assigns a channel and port. 
Finds network address of 
server and does a $QIO 
(l1O$_ACCESS) to port 5000. 


$QIO from the client completes $QIO ACCEPT 
CHANNEL. TRANSPORT_READ_AST is called. 


Translate client’s address to node name. 
Allocate resources (XTCQ, IXTCC, XTCC, 
XTPB, XTCBs). 


Accept connection, drop to user mode, and 
call schedulers CONNECT_REQUEST_NOTIFY 
to see if the server accepts the connection. 


If the server accepts, do a 
$QIO READ for the channel. 


DECW$XPORT_FREE_INPUT_BUFFER 
$QIO READ for this channel. 


Exchange protocol information. 
Continue with client-specific requests. 
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Client 


For example: 
XSEND_AND_GET_REPLY 
(for example, XGetInputFocus) 
DECW$XPORT_COPY_AND_WRITE 


1. REMQHI from 
output free queue. 
Perform data copy. 


2. INSQTI on 
output work queue. 


3. XTFT$A_WRITE 
REMQHI from 


output work queue. 
$QIO WRITE 
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Write AST completion. 


4. INSQTI on 
output free queue. 


DECW$XPORT_READ (Blocking) 
Enable NOTIFY. 
REMOQHI from input work queue. 
lf empty, XPORT_IN_ NOTIFY_WAIT 
and $SYNCH. 





Transport Walk-Through 


Server 


Read completion AST received. 
Exchange protocol information about 
connection. 





Read completion AST received. 

1. Update XTCB’s T z if 
length and ee Spee ic 
pointer. to 7 

Zee 
INSQTI on 1 [2] tot 
input work queue. | Transport-Common 
i 4 oe | 

2. REMQHI from | 
input free queue. 4 a 7 a 
If not empty, do ee Ld 
a $QIO READ for Server Components 
the channel. 


lf NOTIFY enabled, call INPUT_NOTIFY_RTN. 


(Schedule request processing) 
Dispatcher calls DECW$XPORT_READ. 
Enable NOTIFY. 
REMQHI from input work queue. 
If empty, return nothing. 
Otherwise, disable NOTIFY and 
return buffer. 


(Buffer returned so 
process request) 
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Transport Walk-Through 


Generate reply. 
DECW$XPORT_WRITE 
REMGHI from output free queue. 
Perform data copy. 
Calls WRITE_BUFFER. 
[2] INSQTI buffer on output work queue. 
Calls XTFT$A_EXECUTE WRITE. 
[3] REMQHI from output work queue. 
$QIO WRITE. 
[4 ]WRITE_COMPLETION INSQTIs on 
output free queue. 


Transport-Specific 


(Enter read completion AST) 

Update XTCB’s length and pointer. 
INSQTI on input work queue. 

If NOTIFY enabled, send notification. 


REM@QHI on input free queue. 
lf empty and input enabled, $QIO 
READ for data. 


{ 
Transport-Co 


Return 


$SYNCH returns from wait-in-LEF state. 
DECW$XPORT_READ 


tj 2] 
REMQHI from input work queue. = \/ ( 


Server Components 
Dispatcher processes request. When request 
stream exhausted or request is incomplete, 
calls DECW$XPORT_FREE_INPUT_BUFFER. 
XTFT$A_FREE_INPUT_BUFFER 

INSQTI on input free queue. 

If it was empty and input was 

enabled, REMQHI from input free queue. 





Return buffer. 
(Copy reply into user space) 


XCloseDisplay () $QIO READ into buffer. 
DECW$XPORT_CLOSE Return 
XTFT$A_CLOSE : 
$DASSGN CHANNEL ——-—~—»_ (Enter read completion AST) 

Return $QlO READ failed. 
Mark connection as dying. 
Call CONNECT_ABORT_NOTIFY(). 
Return 


(Schedule connection rundown) 
DECW$XPORT_CLOSE 
XTFT$A_CLOSE 
$DASSGN CHANNEL 
Release resources. 
Return 
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5 Transport-Common Routines 


This chapter describes the transport-common routines that are called 
by specific transports. If you write your own transport-specific layer, 
use these routines to allocate the communication queues, allocate and 
deallocate protected memory for structures, initiate read and write 
operations, and so forth. 


Transport-common routines that are called only by other transport- 
common routines or by Xlib and the server are not described in this 
chapter. 


Modifications to the transport-common routines are not recommended or 


supported. 


The transport-common routines are listed in Table 5-1. 


Table 5-1 Transport-Common Routines 


Routine Name 


DECW$XPORT_ACCEPT_FAILED 


DECW$XPORT_ALLOC_INIT_ 
QUEUES 


DECW$XPORT_ALLOC_PMEM 
DECW$XPORT_ATTACHED 
DECW$XPORT_ATTACH_LOST 
DECW$XPORT_CLOSE 


DECW$XPORT_COPY_AND_WRITE 


DECW$XPORT_DEALLOC_PMEM 


DECW$XPORT_DEALLOC_QUEUES 


DECW$$XPORT_FREE_INPUT 
DECW$XPORT_IN_NOTIFY_USER 


DECW$XPORT_REATTACH_FAILED 


Function 
Reports that the transport-specific routines 
could not accept a network link request. 


Allocates storage for an XTCC, XTCQ, and 
all of the XTCBs for a connection. Places 
all of the XTCBs on the appropriate free 
queues. 


Allocation routine for protected structures. 
Reports that a transport is attached. 
Reports that a network has shut down. 


Terminates a connection and releases its 
associated resources. 


Copies data into XTCBs and optionally 
starts a write operation. 


Deallocation routine for protected structures 
allocated with DECW$XPORT_ALLOC_ 
PMEM. 


Deallocates a block of storage previously 
allocated by DECW$XPORT_ALLOC_INIT_ 
QUEUES. 


Initiates a read operation for a connection. 


Notifies Xlib or the server that data on the 
input work queue is available to be read. 


Reports that the transport layer cannot 
continue attempting to reattach. 


(continued on next page) 
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Transport-Common Routines 
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Table 5—1 (Cont.) Transport-Common Routines 


Routine Name 


DECW$XPORT_REFUSED_BY_ 
SERVER 


DECW$XPORT_UNEXPECTED_ 
MESSAG 
DECW$XPORT_UNKNOWN_LINK 
DECW$XPORT_VALIDATE_STRUCT 
DECW$XPORT_VALIDATE_STRUCT_ 


JSB 
DECW$XPORT_VALIDATE_XTCB 


DECW$XPORT_VALIDATE_XTCB_JSB 


DECW$$XPORT_WRITE 


Function 


Reports that the server did not accept a 
connection. 


Reports that an unexpected message was 
received from the underlying transport. 


Reports a message from an unknown 
connection. 


Returns the address of the user write- 
protected IXTCC structure. 


JSB routine that returns the address of the 
user write-protected IXTCC structure. 


Validates that an XTCB is contained within 
the allocated storage for the connection 
and that it is correctly formed. 


JSB routine that validates that an XTCB 
is contained within the allocated storage 
for the connection and that it is correctly 
formed. 


Initiates a writing operation on the 
connection. 


DECWS$XPORT_ACCEPT_FAILED 


DECW$XPORT_ACCEPT_FAILED 


Reports that the transport could not accept a network link request. 





FORMAT 


DECWS$XPORT_ACCEPT_FAILED /ength, address, 
Status 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write 

mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are, listed under Condition Values Returned. 





ARGUMENTS 


length 

VMS usage: longword 

type: longword (unsigned) 

access: read 

mechanism: value 

The length of the connection-failed message string. 


address 

VMS usage: longword 

type: longword (unsigned) 

access: read 

mechanism: value 

The address of the connection-failed message string, which is usually the 
node name of the failed connection. 


status 

VMS usage: longword 

type: longword (unsigned) 

access: read 

mechanism: value 

The condition value of the failed connection. 





DESCRIPTION 


DECW$XPORT_ACCEPT_FAILED builds a message vector that describes 
the nonacceptance of the connection request. The first element in the 
message vector is DECW$_ACCEPT_FAILED; the second element is the 
status argument. 
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DECW$XPORT_ACCEPT FAILED 


The $PUTMSG system service is called in user mode regardless of the 
caller’s mode: 


¢ If DECW$XPORT_ACCEPT_FAILED was called in user mode, it calls 
$PUTMSG to write the error message. 


e If DECW$XPORT_ACCEPT_FAILED was not called in user mode, it 
declares an AST to do the $PUTMSG in user mode. 


DECW$XPORT_ACCEPT_FAILED is called by the TRANSPORT_READ_ 
AST routine in Example 8-15. 





CONDITION SS$_NORMAL Routi full leted 

outine successfully completed. 
VALUES SS$_INSEMEM There is ssa ee roi to perform the operation 
RETURNED ‘ 


Any condition value returned by $PUTMSG. 
Any condition value returned by $DCLAST. 


DECW$XPORT_ALLOC_INIT_QUEUES 


DECW$XPORT _ALLOC INIT QUEUES 


Allocates storage for an XTCC, XTCQ, and all of the XTCBs for a connection. 
Places all of the XTCBs on the appropriate free queues. 





FORMAT DECWS$XPORT_ALLOC_INIT_QUEUES 
itec, xtcc_length, srp_data_length, Irp_data_length, 
e_srp_count, e_Irp_count, r_srp_count, r_Irp_count, 
extra_context_length, extra_context_address 


, 





RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write 


mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are listed under Condition Values Returned. 





ARGUMENTS _ itcc 
VMS usage: record 
type: ixtec 
access: modify 
mechanism: reference 
The IXTCC of the connection for which you want to allocate and initialize 
the queues. The IXTCC$A_TPB field must already be initialized. 


xtcc_length 

VMS usage: longword 

type: longword 

access: read 

mechanism: value 

The length, in bytes, of the XTCC to allocate. May be longer than a 
standard XTCC if the specific transport has appended additional fields. 
Must be at least XTCC$C_LENGTH. 


srp_data_length 

VMS usage: longword 

type: longword 

access: read 

mechanism: value 

The length, in bytes, of the data portion of a small XTCB. No modification 
of the XTCB by specific transports is allowed. 


f 


DECW$XPORT_ALLOC_INIT_QUEUES 


5-6 


Irp_data_length 

VMS usage: longword 

type: longword 

access: read 

mechanism: value 

The length, in bytes, of the data portion of a large XTCB. No modification 
of the XTCB by specific transports is allowed. 


e srp_count 

VMS usage: longword 

type: longword 

access: read 

mechanism: value 

The number of event small XTCBs to allocate. May be 0 or greater. 


e_Irp_count 

VMS usage: longword 

type: longword 

access: read 

mechanism: value 

The number of event large XTCBs to allocate. May be 0 or greater. 


r_srp_count 

VMS usage: longword 

type: longword 

access: read 

mechanism: value 

The number of request small XTCBs to allocate. May be 0 or greater. 


r_Irp_count 


VMS usage: longword 

type: longword 

access: read 

mechanism: value 

The number of request large XTCBs to allocate. May be 0 or greater. 


extra_context_length 

VMS usage: longword 

type: longword 

access: read 

mechanism: value 

The length, in bytes, of the transport-specific space to be allocated. May 
be 0 or greater. 


extra_context_address 

VMS usage: address 

type: longword 

access: write 

mechanism: reference 

The location to receive the address of the extra transport-specific space. 


DECW$XPORT_ALLOC_INIT QUEUES 





DESCRIPTION 


DECW$XPORT_ALLOC_INIT_QUEUES allocates a block of storage for 
an XTCC, XTCQ, and all of the XTCBs for a connection and places all 
of the XTCBs on the appropriate free queues. DECW$XPORT_ALLOC_ 
INIT_QUEUES must allocate at least an XTCC; the other structures are 
optional. 


If no XTCBs are requested, the XTCQ is not allocated. Otherwise, the 
XTCQ is allocated and initialized. The IXTCC is initialized with the 
addresses of the XTCC and the XTCQ, the queue headers, and the queue 
flags. The IXTCC$L_ICI and IXTCC$A_USER_REGION fields are also 
initialized. 

When DECW$XPORT_ALLOC_INIT_QUEUES completes, the status of 
the data structures is as follows: 


Data 
Structure Status 
IXTCC The following fields are initialized: 


*  IXTCC$L_ICI 

* IXTCC$A_TCC 

* IXTCC$A_TCQ 

* IXTCC$A_USER_REGION 
* IXTCC$A_BUFFER_REGION 
¢ IXTCC$A_IW_QUEUE 

¢ IXTCC$A_IFS_QUEUE 

¢  IXTCC$A_IFL_QUEUE 

*  IXTCC$A_OW_QUEUE 

¢ IXTCC$A_OFS_QUEUE 

¢ IXTCC$A_OFL_QUEUE 

¢  IXTCC$L_IWQ_FLAG 

* IXTCC$L_IFSQ_FLAG 

¢  IXTCC$L_IFLQ_FLAG 

°  IXTCC$L_OWQ_FLAG 

¢ IXTCC$L_OFSQ_FLAG 

¢ IXTCC$L_OFLQ_FLAG 
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DECW$XPORT_ALLOC_INIT_QUEUES 


Data 
Structure Status 
XTCC The following fields are initialized: 
* XTCC$W_SIZE 
* XTCC$B_TYPE 
¢* XTCC$B_SUBTYPE 
* XTCC$A_TPB 
* XTCC$A_TCQ 
* XTCC$L_ICI 
* XTCC$A_IW_QUEUE 
¢ XTCC$A_IFS_QUEUE 
¢ XTCC$A_IFL_QUEUVE 
* XTCC$A_OW_QUEUE 
* XTCC$A_OFS_QUEUE 
* XTCC$A_OFL_QUEUE 
* XTCC$A_TCQ_FLAGS 
« XTCC$L_IWQ_FLAG 
° XTCC$L_IFSQ_FLAG 
* XTCC$L_IFLQ_FLAG 
* XTCC$L_OWQ_FLAG 
* XTCC$L_OFSQ_FLAG 
* XTCC$L_OFLQ_FLAG 
XTCBs Completely initialized 
XTCQ Completely initialized 


DECW$XPORT_ALLOC_INIT_QUEUES may be called only from 
executive mode. 





CONDITION SS$_NORMAL Routi full leted 
outine successfully completed. 
VALUES - ee 
RETURNED DECW$_NOT_INITIALIZED The common transport is not initialized. 
DECW$_BADQUEUE A queue was corrupted during initialization. 


DECW$XPORT_ALLOC_PMEM 


DECW$XPORT ALLOC PMEM 


Allocation routine for protected structures. 





FORMAT 


status_return=DECW$XPORT_ALLOC PMEM size, 
sub- 


type 





RETURNS 


VMS usage: address 
type: longword 
access: write 
mechanism: value 


Returns 0 on failure, and a nonzero address of allocated storage if 
successful. 





ARGUMENTS 


size 

VMS usage: longword 

type: longword 

access: read 

mechanism: value 

The size of the memory block to allocate, in bytes. 


subtype 

VMS usage: longword 

type: longword 

access: read 

mechanism: value 

User-defined subtype field used to initialize the final byte of the third 
longword. 





DESCRIPTION 


DECW$XPORT_ALLOC_PMEM is an allocation routine for protected 
structures. The sample transport calls DECW$XPORT_ALLOC_PMEM to 
allocate IXTCCs and XTPBs, structures that must not be modified by user- 
mode code. DECW$XPORT_ALLOC_PMEM allocates a block of storage of 
the size that you specify. The block is assumed to begin with a 3-longword 
structure prefix; the length, type, and subtype fields in the third longword 
are initialized to appropriate values. 


DECW$XPORT_ALLOC_PMEM is called only from executive mode. The 
allocated memory is protected as user-read/executive-write (UREW). 
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DECW$XPORT_ATTACHED 


DECWS$XPORT_ATTACHED 


Reports that a transport is attached. 








FORMAT DECWS$XPORT_ATTACHED idb 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write 


mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are listed under Condition Values Returned. 





ARGUMENT idb 


VMS usage: record 

type: xtdb 

access: modify 

mechanism: reference 

The XTDB of the transport that is attached. 





DESCRIPTION DECW$XPORT_ATTACHED builds a message vector that describes 
the attached transport. The only element of the vector is DECW$_ 
ATTACHED. 


The $PUTMSG system service is called in user mode regardless of the 
caller’s mode: 


e If DECW$XPORT_ATTACHED was called in user mode, it calls 
$PUTMSG to write the message. 


e If DECW$XPORT_ATTACHED was not called in user mode, it declares 
a user-mode AST to do the $PUTMSG. 





CONDITION 

SS$_NORMAL Routine successfully completed. 
VALUES SS$_INSFMEM There is insufficient memory to perform the operation 
RETURNED ~ 


Any condition value returned by $PUTMSG. 
Any condition value returned by $DCLAST. 


t 
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DECW$XPORT_ATTACH_LOST 


DECWS$XPORT_ATTACH_LOST 


Reports that a network has shut down. 








FORMAT DECW$XPORT_ATTACH_LOST tdb, status 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write 


mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are listed under Condition Values Returned. 





ARGUMENTS _ itdb 
VMS usage: record 
type: xtdb 
access: modify 
mechanism: reference 
The XTDB of the transport that shut down. 


status 

VMS usage: longword 

type: longword (unsigned) 
access: read 


mechanism: value 
The condition value of the transport that is shutting down. 





DESCRIPTION DECW$XPORT_ATTACH_LOST builds a message vector that describes 
the network shutdown. The first element in the message vector is 
DECW$_ATTACH_LOST; the second element is the status argument. 


The $PUTMSG system service is called in user mode regardless of the 
caller’s mode: 


¢ If DECW$XPORT_ATTACH_LOST was called in user mode, it calls 
$PUTMSG to write the message. 


¢ If DECW$XPORT_ATTACH_LOST was not called in user mode, it 
declares a user-mode AST to do the $PUTMSG. 





CONDITION SS$_NORMAL Routi ccessfully completed 

outine successfu . 
VALUES SS$_INSFMEM There is eee to perform the operation 
RETURNED : | 


Any condition value returned by $PUTMSG. 
Any condition value returned by $DCLAST. 
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DECW$XPORT_CLOSE 


DECW$XPORT_CLOSE 


Terminates a connection and releases its associated resources. 





FORMAT DECW$XPORT_CLOSE icc 





ARGUMENTS _ tcc 
VMS usage: record 
type: xtcc 
access: modify 
mechanism: reference 
The XTCC of the connection to close. 





DESCRIPTION DECW$XPORT_CLOSE terminates a connection and releases its 
associated resources. The transport user is expected to return any XTCBs 
acquired through DECW$XPORT_READ and DECW$XPORT_GET_ 
OUTPUT_BUFFER before calling DECW$XPORT_CLOSE. After calling 
DECW$XPORT_CLOSE, the structures used by the connection (XTCC, 
XTCQ, and XTCBs) must not be referenced. 


The DECW$XPORT_CLOSE routine calls the transport-specific connection 
close routine, XTFT$A_CLOSE, to actually break the network link. 
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DECW$XPORT_COPY_AND_ WRITE 


DECWS$XPORT_COPY_AND_WRITE 


Copies data into XTCBs and optionally starts a write operation. 








FORMAT DECW$XPORT_COPY_AND_ WRITE tcc, mode, 
buffer, buflen, 
retbuflen, 
padbytes 

RETURNS VMS usage: cond_value 

type: longword (unsigned) 
access: write 


mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are listed under Condition Values Returned. 





ARGUMENTS __ icc 
VMS usage: record 
type: xtcc 
access: modify 
mechanism: reference 
The XTCC of the connection from which you want to write. 


mode 

VMS usage: longword 
type: longword 
access: read 


mechanism: value 
Modifying flags for the write operation. The valid fields are: 


Constant Description 





DECW$M_MODE_NOBLOCK Nonblocking write. When the DECW$M_MODE_ 
NOBLOCK flag is set, any attempt to get a 
transport buffer when none is available causes the 
the call to return the status DECW$_BUFNOTAVL 
and perform only a partial write operation. 


When this bit is clear and a nonzero timeout 
value was specified in DECWS$XPORT_ATTACH_ 
TRANSPORT, getting a buffer can time out, 
causing this routine to return with the DECW$_ 
BUFFERTIMEOUT status. 
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DECW$XPORT_COPY_AND_WRITE 


Constant Description 
DECW$M_MODE_ If the specific transport was blocked for the XTCB 
NOWRTBLOCK write operation, the last XTCB is placed on the 


work queue and DECW$XPORT_COPY_AND_ 
WRITE returns with a DECW$_BLOCKED status. 


buffer 

VMS usage: char string 
type: char string 
access: read 


mechanism: reference 
A buffer in the user’s address space that contains data to write to the 


connection. 

buflen 

VMS usage: longword 
type: longword 
access: read 


mechanism: value 
The length of the data in the buffer. 


retbuflen 

VMS usage: longword 
type: longword 
access: write 


mechanism: reference 

Address of longword to receive the amount of data that was actually 
written to the connection. If DECW$M_MODE_NOBLOCK was not set 
in the mode argument, and there is no timeout, retbuflen is always the 
amount requested. 


padbytes 

VMS usage: longword 
type: longword 
access: read 


mechanism: value 
Number of pad bytes (zeros) to append to the copy. 





DESCRIPTION DECW$XPORT_COPY_AND_WRITE performs a buffered write operation 
and returns the size of the data actually copied in the retbuflen 
argument. Data from the user’s buffer is always copied to transport 
buffers prior to processing by the transport-specific write function. 


The sample transport calls DECW$XPORT_COPY_AND_WRITE from the 
XTFT$A_WRITE_USER routine. 


DECW$XPORT_COPY_AND_WRITE must be called in user mode. 
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DECW$XPORT_COPY_AND WRITE 





CONDITION 
SS$_NORMAL Routine successfully completed. 

VALUES ; 

RETURNED SS$_ACCVIO XTCC is not user-readable. 
SS$_BADPARAM XTCC argument is not an XTCC. 
DECW$_CNXABORT Connection is in abort condition. 
DECW$_RECIO_OPE Recursive |/O operation. 
DECW$_BLOCKED The transport blocked the write operation. 


DECW$_BUFFERTIMEOUT __ Timed out while waiting for buffer. 
DECW$_NOT_INITIALIZED The common transport is not initialized. 
DECW$_INV_STRUCT_ID The XTCC$L_ICI field is not valid. 


May also return any other status set in the XTCC$L_ERR_STATUS field 
if the connection is aborting. 
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DECW$XPORT_DEALLOC_PMEM 


DECW$XPORT DEALLOC PMEM 


Deallocation routine for protected structures allocated with DECW$XPORT_ 
ALLOC_PMEM. 





FORMAT DECW$XPORT_DEALLOC_PMEM buffer 





ARGUMENTS _ buffer 
VMS usage: address 
type: longword 
access: read 
mechanism: value 
The address of the buffer to deallocate. 





DESCRIPTION DECW$XPORT_DEALLOC_PMEM deallocates a structure that was 
previously allocated by DECW$XPORT_ALLOC_PMEM. Any errors are 
signaled. DECW$XPORT_DEALLOC_PMEM does not return a condition 
value. 


DECW$XPORT_DEALLOC_PMEM must be called in executive mode. 
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DECW$XPORT_DEALLOC_QUEUES 


DECW$XPORT DEALLOC QUEUES 


Deallocates a block of storage previously allocated by DECW$XPORT_ 
ALLOC_INIT_QUEUES. 








FORMAT DECW$XPORT_DEALLOC QUEUES itcc 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write 


mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are listed under Condition Values Returned. 





ARGUMENTS _ iicc 
VMS usage: record 
type: ixtcc 
access: modify 
mechanism: reference 
The IXTCC of the connection for which you want to deallocate a block of 
storage previously allocated for the queues. 





DESCRIPTION DECW$XPORT_DEALLOC_QUEUES deallocates a block of storage that 
was previously allocated for the queues of a connection by DECW$XPORT._ 
ALLOC_INIT_QUEUES. 


DECW$XPORT_DEALLOC_QUEUES must be called in executive mode. 





CONDITION | 
VALUES SS$_NORMAL Routine successfully completed. 

DECW$_NOT_INITIALIZED = The common transport is not initialized. 
RETURNED 


DECW$$XPORT_FREE_INPUT 


DECWS$$XPORT_FREE_INPUT 


Initiates a read operation on the connection. 








FORMAT DECW$$XPORT_FREE_INPUT tcc, tcb 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write 


mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are listed under Condition Values Returned. 





ARGUMENTS __ fcc 
VMS usage: record 
type: xtcc 
access: modify 
mechanism: reference 
The XTCC of the connection from which you want to read. 


tcb 

VMS usage: record 
type: xtcb 
access: modify 


mechanism: reference 
DECW$$XPORT_FREE_INPUT initiates a read operation for the 
connection into this XTCB. 





DESCRIPTION The DECW$$XPORT_FREE_INPUT system service calls the XTFT$A_ 
FREE_INPUT_BUFFER routine in executive mode to perform an 
asynchronous read operation for the connection. The read operation is 
performed asynchronously to avoid waiting for it to complete. 


The XTFT$A_FREE_INPUT_BUFFER routine does the actual read 
operation for the connection into the XTCB specified in the tcb argument. 
If the read operation fails, XTFT$A_FREE_INPUT_BUFFER inserts the 
XTCB on the free queue and sets the connection state to dying. 


DECW$$XPORT_FREE_INPUT is an executive-mode routine. 





CONDITION SS$ NORMAL Routi full leted 

outine successfully completed. 
VALUES DECWS CNXABORT Connection is in 2. ane 
RETURNED 5 : 


5-18 


DECW$XPORT_IN_NOTIFY_USER 


DECW$XPORT_IN NOTIFY USER 


Notifies Xlib or the server that data on the input work queue is available to be 
read. 





FORMAT 


DECWS$XPORT_IN_NOTIFY_USER icc 





ARGUMENT 


tcc 

VMS usage: record 

type: xtcc 

access: modify 

mechanism: reference 

The XTCC of the connection for which you want to limit input-notify AST 
delivery. 





DESCRIPTION 


DECW$XPORT_IN_NOTIFY_USER clears the XTCC$V_IN_AST_IN_ 
PROG bit in the XTCC to indicate that the AST has been delivered, 
and calls the input notification procedure, identified by the XTPB$A_I_ 
NOTIFY_RTNADR field. 


Transport users may request notification of input data. One method 
of notifying transport users is to deliver an AST that calls the user’s 
XTPB$A_I_NOTIFY_RTNADR procedure with the XTCC as an argument. 


It is possible for a large number of read operations to complete before 
the first notification AST is delivered, particularly if an Xlib application 
is executing at user-AST level for a long period of time, or not reading 
events. 


If ASTs were declared without regard for whether they were being 
delivered, it is possible to exceed the process AST quota. DECW$XPORT_ 
IN_NOTIFY_USER and the XPORT_IN_NOTIFY_SEND macro provide a 
mechanism for limiting AST use. 


The XPORT_IN_NOTIFY_SEND macro tests and sets the XTCC$V_ 
IN_AST_IN_PROG bit. If it was set, there is already a notification 
AST waiting to be delivered. If the XTCC$V_IN_AST_IN_PROG bit 
was clear, XPORT_IN_NOTIFY_SEND declares a user-mode AST to call 
DECW$XPORT_IN_NOTIFY_USER. 


DECW$XPORT_IN_NOTIFY_USER clears the XTCC$V_IN_AST_IN_ 
PROG bit and then calls the user’s XTPB$A_I_NOTIFY_RTNADR 
procedure. 


DECW$XPORT_IN_NOTIFY_USER is called in user mode. 
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DECWS$XPORT_REATTACH_FAILED 


DECWS$XPORT_REATTACH_FAILED 


Reports that the transport layer cannot continue attempting to reattach a 








transport. 
FORMAT DECWS$XPORT_REATTACH_FAILED tab, status 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write 


mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are listed under Condition Values Returned. 





ARGUMENTS __ idb 
VMS usage: record 
type: xtdb 
access: modify 
mechanism: reference 
The XTDB of the transport to which the transport layer cannot continue 
attempting to reattach. 


status 

VMS usage: longword 

type: longword (unsigned) 
access: read 


mechanism: value 
The condition value of the failed reattach attempt. 





DESCRIPTION DECW$XPORT_REATTACH_FAILED builds a message vector that 
describes the failed reattach attempt. The first element in the message 
vector is DECW$_REATTACH_FAILED; the second element is the status 
argument. 

When a transport shuts down, a specific transport can attempt to reattach 


that transport. If the specific transport is then unable to complete the 
reattach attempt, DECW$XPORT_REATTACH_FAILED is called. 


The $PUTMSG system service is called in user mode regardless of the 
caller’s mode: 


e If DECW$XPORT_REATTACH_FAILED was called in user mode, it 
calls $PUTMSG to write the error message. 


e If DECW$XPORT_REATTACH_FAILED was not called in user mode, 
it declares a user-mode AST to do the $PUTMSG. 


DECW$XPORT_REATTACH_FAILED 





CONDITION | 

SS$_NORMAL Routine successfully completed. 
VALUES SS$_INSFMEM There is insufficient memory to perform the operation 
RETURNED = 


Any condition value returned by $PUTMSG. 
Any condition value returned by $DCLAST. 
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DECW$XPORT_REFUSED_ BY SERVER 


DECW$XPORT_REFUSED BY SERVER 


Reports that the server rejected a connection request. 








FORMAT DECWS$XPORT_REFUSED BY SERVER status 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write 


mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are listed under Condition Values Returned. 





ARGUMENT status 
VMS usage: longword 
type: longword (unsigned) 
access: read 
mechanism: value 
The condition value of the server’s rejection. 





DESCRIPTION DECW$XPORT_REFUSED_BY_SERVER builds a message vector that 
describes the server’s rejection of a connection request. The first element 
in the message vector is DECW$_REFUSED_BY_SERVER; the second 
element is the status argument. 


The $PUTMSG system service is called in user mode regardless of the 
caller’s mode: 


¢ If DECW$XPORT_REFUSED_BY_SERVER was called in user mode, 
it calls $PUTMSG to write the error message. 


e If DECW$XPORT_REFUSED_BY_SERVER was not called in user 
mode, it declares a user-mode AST to do the $PUTMSG. 





CONDITION 

SS$_NORMAL Routine successfully completed. 
VALUES SS$_INSFMEM There is insufficient memory to perform the operation 
RETURNED ‘. 


Any condition value returned by $PUTMSG. 
Any condition value returned by $DCLAST. 
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DECW$XPORT_UNEXPECTED_MESSAG 


DECW$XPORT_UNEXPECTED_MESSAG 


Reports that an unexpected message was received from the underlying 








transport. 
FORMAT DECW$XPORT_UNEXPECTED MESSAG _ type 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write 


mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are listed under Condition Values Returned. 





ARGUMENT type 
VMS usage: longword 
type: longword (unsigned) 
access: read 
mechanism: value 
The type of the unexpected message. 





DESCRIPTION DECW$XPORT_UNEXPECTED_MESSAG builds a message vector that 
describes an unexpected message. The only element in the message vector 
is DECW$_UNEXPECTED_MESSAGE. 


The $PUTMSG system service is called in user mode regardless of the 
caller’s mode: 


e If DECW$XPORT_UNEXPECTED_MESSAG was called in user mode, 
it calls $PUTMSG to write the error message. 


e If DECW$XPORT_UNEXPECTED_MESSAG was not called in user 
mode, it declares an AST to do the $PUTMSG. 


DECW$XPORT_UNEXPECTED_MESSAG is currently used only by the 





DECnet transport. 
CONDITION 

SS$_NORMAL Routine successfully completed. 
VALUES SS$_INSFMEM There is insufficient memory to perform the operation 
RETURNED : 


Any condition value returned by $PUTMSG. 
Any condition value returned by $DCLAST. 
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DECW$XPORT_UNKNOWN_LINK 


DECW$XPORT_UNKNOWN_LINK 


Reports a message about an unknown connection from the underlying 








transport. 
FORMAT DECWS$XPORT_UNKNOWN _LINK unit 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write 


mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are listed under Condition Values Returned. 





ARGUMENT unit 
VMS usage: longword 
type: longword (unsigned) 
access: read 
mechanism: value 
The unknown link’s unit number. 





DESCRIPTION DECW$XPORT_UNKNOWN_LINK builds a message vector that describes 
an unknown connection. The only element of the vector is DECW$_ 
UNKNOWN_LINK. 


The $PUTMSG system service is called in user mode regardless of the 
caller’s mode: 


e If DECW$XPORT_UNKNOWN_LINK was called in user mode, it calls 
$PUTMSG to write the error message. 


¢ If DECW$XPORT_UNKNOWN_LINK was not called in user mode, it 
declares a user-mode AST to do the $PUTMSG. 


DECW$XPORT_UNKNOWN_LINK is currently used only by the DECnet 





transport. 
CONDITION 

SS$_NORMAL Routine successfully completed. 
VALUES SS$_INSFMEM There is insufficient memory to perform the operation 
RETURNED = 


Any condition value returned by $PUTMSG. 
Any condition value returned by $DCLAST. 


i 
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DECW$XPORT_VALIDATE_STRUCT 


DECWS$XPORT_VALIDATE_STRUCT 


Returns the address of the user write-protected IXTCC structure. 








FORMAT DECW$XPORT_VALIDATE_STRUCT id, siruct 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write 


mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are listed under Condition Values Returned. 





ARGUMENTS __— id 
VMS usage: longword 
type: longword (unsigned) 
access: read 
mechanism: value 
A previously registered IXTCC structure ID (XTCC$L_ICI). 


struct 

VMS usage: address 
type: ixtcc 
access: write 


mechanism: reference 
Returns the address of the user write-protected IXTCC structure. 





DESCRIPTION DECWS$XPORT_VALIDATE_STRUCT checks the user write-protected 
IXTCC structure ID and, if valid, returns its corresponding address. 
DECW$XPORT_VALIDATE_STRUCT invokes the DECW$XPORT_ 
VALIDATE_STRUCT_JSB routine for callers using CALLS. 


DECW$XPORT_VALIDATE_ STRUCT is called in both user and executive 





modes. 
CONDITION | 
VALUES SS$_NORMAL Routine successfully completed. 
DECW$_NOT_INITIALIZED The common transport is not initialized. 
RETURNED 


DECW$_INV_STRUCT_ID The structure ID is not valid. 
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DECW$XPORT_VALIDATE_STRUCT_JSB 


DECW$XPORT_VALIDATE STRUCT JSB 


JSB routine that returns the address of the user write-protected IXTCC 








structure. 
FORMAT DECW$XPORT_VALIDATE_STRUCT _ id, struct 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write 


mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are listed under Condition Values Returned. 





ARGUMENTS id 
VMS usage: longword 
type: longword (unsigned) 
access: read 
mechanism: value 
A previously registered IXTCC structure ID (XTCC$L_ICI). 


struct 

VMS usage: address 
type: ixtec 
access: write 


mechanism: reference 
Returns the address of the user write-protected IXTCC structure. 





DESCRIPTION DECW$XPORT_VALIDATE_STRUCT_JSB checks the ID of the user 
write-protected IXTCC structure. If a structure exists with that ID, 
DECW$XPORT_VALIDATE_STRUCT_JSB returns its corresponding 
address in the struct argument. 


The VALIDATE_XTCC macro calls the DECW$XPORT_VALIDATE_ 
STRUCT_JSB routine to validate an XTCC. 


DECW$XPORT_VALIDATE_STRUCT_JSB is called in both user and 
executive modes. 





CONDITION SS$_NORMAL Routi full leted 

utine successfully completed. 
VALUES DECWS NOT_INITIALIZED The common aioe is its initialized 
RETURNED ye 


DECW$_INV_STRUCT_ID The structure ID is not valid. 


DECW$XPORT_VALIDATE_XTCB 


DECW$XPORT VALIDATE XTCB 


Validates that an XTCB is contained within the allocated storage for the 
connection and that it is correctly formed. 





FORMAT 


DECW$XPORT_VALIDATE_XTCB _itcc, tcb 





RETURNS 


VMS usage: cond_value 

type: longword(unsigned) 
access: write 

mechanism: value 


Returns a longword condition value to RO. Possible condition values are 
listed under Condition Values Returned. 





ARGUMENTS 


itcc 

VMS usage: record 

type: ixtec 

access: modify 

mechanism: reference 

The IXTCC of the connection for which you want to validate the XTCB. 


tcb 


VMS usage: record 

type: xtcb 

access: modify 

mechanism: reference 

The XTCB that you want to validate. 





DESCRIPTION 


DECW$XPORT_VALIDATE_XTCB invokes DECW$XPORT_VALIDATE_ 
XTCB_JSB for callers using CALLS. 

DECW$XPORT_VALIDATE_XTCB validates that an XTCB is contained 
within the allocated buffer storage for the connection and that it is 
correctly formed. 


Either DECW$XPORT_VALIDATE_XTCB or DECW$XPORT_VALIDATE_ 
XTCB_JSB must be called before an XTCB is used in executive mode. 


DECW$XPORT_VALIDATE_XTCB may be called in both user and 
executive modes. 


DECW$XPORT_VALIDATE_XTCB 





CONDITION 

V ALUES SS$_NORMAL Routine successfully completed. 
DECW$_NOT_INITIALIZED The common transport is not initialized. 

RETURNED DECW$_NOT_XTCB The XTCB is not in the buffer region. 
DECW$_ILLFORMED_XTCB The XTCB header is not valid. 
SS$_IVBUFLEN The XTCB length field is not valid. 
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DECW$XPORT_VALIDATE_XTCB_JSB 


DECWS$XPORT_VALIDATE_XTCB_JSB 


JSB routine that validates that an XTCB is contained within the allocated 
storage for the connection and that it is correctly formed. 





FORMAT 


DECW$XPORT_VALIDATE_XTCB_JSB tcc, tcb 





RETURNS 


VMS usage: cond_value 

type: longword(unsigned) 
access: write 

mechanism: value 


Returns a longword condition value to RO. Possible condition values are 
listed under Condition Values Returned. 





ARGUMENTS 


lice 

VMS usage: record 

type: ixtcc 

access: modify 

mechanism: reference 

The IXTCC of the connection for which you want to validate the XTCB. 


tcb 


VMS usage: record 

type: xtcb 

access: modify 

mechanism: reference 

The XTCB that you want to validate. 





DESCRIPTION 


DECW$XPORT_VALIDATE_XTCB_JSB validates that an XTCB is 
contained within the allocated buffer storage for the connection and 
that it is correctly formed. 


Either DECW$XPORT_VALIDATE_XTCB_JSB or DECW$XPORT_ 
VALIDATE_XTCB must be called before an XTCB is used in executive 
mode. 


DECW$XPORT_VALIDATE_XTCB_JSB may be called in both user and 
executive modes. 


DECW$XPORT_VALIDATE_XTCB_JSB 





CONDITION 

V ALUES SS$_ NORMAL Routine successfully completed. 
DECW$_NOT_INITIALIZED The common transport is not initialized. 

RETURNED DECW$_NOT_XTCB The XTCB is not in the buffer region. 
DECW$_ILLFORMED_XTCB The XTCB header is not valid. 
SS$_IVBUFLEN The XTCB length field is not valid. 
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DECW$$XPORT_WRITE 


DECW$$XPORT_WRITE 


Initiates a write operation on the connection. 





FORMAT 


DECWS$$XPORT_WRITE tcc, xtcb, mode 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write 

mechanism: value 


Returns a longword condition value in RO. Condition values returned by 
this routine are listed under Condition Values Returned. 





ARGUMENTS 


tcc 

VMS usage: record 

type: xtcc 

access: modify 

mechanism: reference 

The XTCC of the connection from which you want to write. 


xtcb 

VMS usage: record 
type: xtcb 
access: modify 


mechanism: reference 
The XTCB you want to write to the connection. 


mode 

VMS usage: longword 
type: longword 
access: read 


mechanism: value 
Modifying flags for the write operation. The valid field is: 


Constant Description 
DECW$M_MODE_ If the specific transport was blocked for the XTCB 
NOWRTBLOCK write operation, DECW$$XPORT_WRITE returns 


with a DECW$_BLOCKED status. 


5-31 


DECW$$XPORT_WRITE 





DESCRIPTION The system service DECW$$XPORT_WRITE initiates a write operation 
on the connection associated with an XTCC. DECW$$XPORT_WRITE 
dispatches a write operation to the transport-specific write function. 


DECW$$XPORT_WRITE calls the VALIDATE_XTCC macro to validate 

the XTCC. If it is valid, DECW$$XPORT_WRITE gets the XTFT from the 

IXTCC$A_XPORT_TABLE field and calls the transport-specific XTFT$A_ 
, WRITE routine in executive mode to actually write the XTCB. 





CONDITION 

VALUES SS$_NORMAL Routine Seneeny complet: 
DECW$_CNXABORT Connection is in abort condition. 

RETURNED DECW$_RECIO_OPE Recursive I/O operation. 
DECW$_BLOCKED The transport blocked the write operation. 


5-32 





6 Transport-Specific Routines 


This chapter describes the transport-specific routines that you must 
implement if you write your own transport-specific component. 


Most of the routines described in this chapter are called by the transport- 
common code through the XTFT data structure. However, this chapter 
also describes supporting routines, such as AST completion routines, that 
you must write if your transport design requires it. 


The transport-specific routines are listed in Table 6—1. 


Table 6-1 Transport-Specific Routines 


Routine 


CLOSE_AND_DEALLOCATE_AST 
DECW$TRANSPORT_INIT 
DETACH_AND_POLL 
FREE_INPUT_AST 


REATTACH_AST 


TRANSPORT_OPEN_CALLBACK 


TRANSPORT_READ_AST 


TRANSPORT_READ_QUEUE 
WRITE_AST 
XTFT$A_AT TACH_TRANSPORT 


XTFT$A_CLOSE 
XTFT$A_EXECUTE_FREE 
XTFT$A_EXECUTE_WRITE 


XTFT$A_FREE_INPUT_BUFFER 


Function 

Completes the connection close initiated by 
XTFT$A_CLOSE. Internal to specific transport. 
Initializes and returns the XTFT data structure. 


Detaches from the transport and starts polling 
for a transport restart. Internal to specific 
transport. 


AST completion routine for transport read 
operations. Internal to specific transport. 


Attempts to reattach the transport when the 
timer interval has expired. Internal to specific 
transport. 


Performs a callback to the client during the 
connection-open sequence. Internal to specific 
transport. 


Read-completion AST routine for the 
transport’s network channel. Internal to 
specific transport. 


Initiates an asynchronous connection-accept 
operation. Internal to specific transport. 


AST completion routine for transport write 
operations. Internal to specific transport. 


Performs the transport-specific initialization 
functions. 


Closes a transport connection. 
Returns an XTCB to a local connection. 


Writes an XTCB to a transport-specific 
connection. 


Starts a read operation on a freed input buffer. 


(continued on next page) 
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Transport-Specific Routines 


Table 6-1 (Cont.) Transport-Specific Routines 


Routine Function 

XTFT$A_OPEN Attempts to establish a connection to a server. 

XTFT$A_RUNDOWN Performs the transport-specific rundown 
functions required during image rundown. 

XTFT$A_WRITE Writes an XTCB buffer from the common 
transport to a transport-specific connection. 

XTFT$A_WRITE_USER Attempts to write a buffer in the user’s address 


space to a transport-specific connection. 


The routine descriptions document the generic functions that the 
transport-common component expects the transport-specific routines 

to perform. Your implementation of the routines depends on your 
underlying transport and may therefore differ in details. However, 
your implementation of the routines must fullfill the transport-common 
expectations. 


See Chapter 8 for examples of TCP/IP implementations of these routines. 





6.1 Condition Values 
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When a transport-specific routine finishes execution, a numeric status 
value is returned in RO. This status value is returned as the status 
value of the transport-common routine. Your implementation of the 
transport-specific routines can return any valid VMS condition value. 


CLOSE_AND_DEALLOCATE_AST 


CLOSE AND DEALLOCATE AST 


Completes the connection close initiated by XTFT$A_CLOSE. Internal to 
specific transport. 





FORMAT 


CLOSE AND _DEALLOCATE_AST iicc 





ARGUMENT 


itec 

VMS usage: record 

type: ixtec 

access: modify 

mechanism: reference 

The IXTCC of the connection to close. 





DESCRIPTION 


The CLOSE_AND_DEALLOCATE_AST routine is invoked as an AST by 
the XTFT$A_CLOSE routine to complete the connection-close process. 
Once CLOSE_AND_DEALLOCATE_AST executes, it is assumed that 
neither the transport caller nor any part of transport will refer to this 
connection again. 


CLOSE_AND_DEALLOCATE_AST removes the IXTCC from the IXTCC 
queue in the XTDB, decrements the reference count in the XTDB, and 
releases the XTCBs on the communication queue. 


CLOSE_AND_DEALLOCATE_AST also zeroes various fields in the XTCC 
and IXTCC to catch any subsequent references to the connection and 
deallocates the remaining connection structures. 


CLOSE_AND_DEALLOCATE_AST is invoked in executive mode. 


Section 8.3.10 shows a sample implementation of the CLOSE_AND_ 
DEALLOCATE_AST routine. 
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DECWS$TRANSPORT_INIT 


DECW$TRANSPORT_INIT 


Initializes and returns the XTFT data structure. 








FORMAT xtft-DECW$TRANSPORT_INIT 
RETURNS VMS usage: record 

type: xtft 

access: write 


mechanism: reference 


Returns a pointer to the XTFT data structure. 





ARGUMENTS = None. 





DESCRIPTION DECWS$TRANSPORT_INIT initializes and returns the XTFT data 
structure through which the transport-specific routines are called. 


The common transport must always be able to find the transport-specific 
XTFT structures. To ensure that the common transport can find the 
XTFT structures, all specific transports provide a transfer vector to the 
DECW$TRANSPORT_INIT routine as the first image section in the 
specific transport shareable image. 


The DECW$XPORT_ATTACH_TRANSPORT routine calls 
DECW$TRANSPORT_INIT to initialize and return the XTFT data 
structure. Once the XTFT is initialized, DECW$XPORT_ATTACH_ 
TRANSPORT calls the XTFT$A_ATTACH TRANSPORT routine to 
complete the transport-specific initialization. 


The DECW$TRANSPORT INIT routine is called in executive mode. 


See Section 8.3.19 for a sample implementation of the 
DECW$TRANSPORT_INIT routine and the associated transfer vector. 


[ 


DETACH_AND_POLL 





DETACH AND POLL 


Detaches from the transport and starts polling for a transport restart. Internal 
to specific transport. 








FORMAT DETACH_AND_ POLL idb 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write 


mechanism: value 


Returns a longword condition value in RO. 





ARGUMENT tdb 
VMS usage: record 
type: xtdb 
access: modify 
mechanism: reference 
The XTDB of the transport that you want to poll. 





DESCRIPTION The DETACH_AND_POLL routine releases the transport’s connection- 
specific and connection-accept channels and then polls the transport to 
attempt a restart. DETACH_AND_POLL does not attempt to restart the 
transport if the XTDB$V_DYING bit is set. If it is unable to poll for the 
restart, DETACH_AND_POLL reports that the reattach attempt failed. 


DETACH_AND_POLL is invoked in executive mode. 


See Section 8.3.16 for a sample implementation of the DETACH_AND_ 
POLL routine. 


FREE_INPUT_AST 


FREE INPUT AST 


AST completion routine for transport read operations. Internal to specific 
transport. 





FORMAT 


FREE_INPUT_AST xicb 





ARGUMENT 


xtcb 

VMS usage: record 

type: xtcb 

access: modify 

mechanism: reference 

The XTCB to insert on the input work queue. 





DESCRIPTION 


FREE_INPUT_AST is used by the XTFT$A_FREE_INPUT_BUFFER 
routine with the XTCB buffer returned by the $QIO read. FREE_INPUT_ 
AST inserts this XTCB on the tail of the input work queue and then 
attempts to remove a free input buffer and initiate a $QIO read into it. 


FREE_INPUT_AST must check if this connection is aborting or the I/O 
failed, and if so, perform failure processing. If FREE_INPUT_AST is the 
first to set the dying bit, it must also perform abort notification. Abort 
notification consists of conditionally declaring a user-mode AST for the 
link abort (by means of XPORT_ABORT_SEND), sending notification that 
a write operation has completed to complete any output wait condition, 
and sending notification that a read operation has completed to complete 
any input wait condition. 


FREE_INPUT_AST also determines whether the large or small XTCBs 
should be used in subsequent I/O operations. If the $QIO read operation 
that just completed filled a small request packet, FREE_INPUT_AST uses 
the large request packet. If large XTCBs were being used and the last 
read operation would have fit in a small XTCB, FREE_INPUT_AST shifts 
down to the small XTCBs. 


FREE_INPUT_AST then attempts to remove an XTCB from the free 
queue and initiate a $QIO read operation into it. FREE_INPUT_AST 
specifies itself as the read-completion routine. If the $QIO read operation 
fails, FREE_INPUT_AST marks the connection as dying and performs 
connection-abort processing. 


FREE_INPUT_AST is invoked in user or executive mode. 


See Section 8.3.8 for a sample implementation of the FREE_INPUT_AST 
routine. 


REATTACH_AST 


REATTACH_ AST 


Attempts to reattach the transport when the timer interval has expired. Internal 
to specific transport. 








FORMAT REATTACH_AST  itdb 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write 


mechanism: value 


Returns a longword condition value in RO. 





ARGUMENT tdb 
VMS usage: record 
type: xtdb 
access: modify 
mechanism: reference 
The XTDB of the transport that you want to reattach. 





DESCRIPTION REATTACH_AST is the AST completion routine for the $SETIMR system 
service invoked by the DETACH_AND_POLL routine. REATTACH_AST 
calls the transport-specific XTFT$A_ATTACH_TRANSPORT routine to 
reattach the transport. 


REATTACH_AST is invoked in executive mode. 


See Section 8.3.17 for a sample implementation of the REATTACH_AST 
routine. 
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TRANSPORT_OPEN_CALLBACK 


TRANSPORT_OPEN_CALLBACK 


Performs a callback to the client during the connection-open sequence. 
Internal to specific transport. 





FORMAT 


TRANSPORT_OPEN_CALLBACK _itcc 





ARGUMENT 


itcc 

VMS usage: record 

type: ixtcc 

access: modify 

mechanism: reference 

The IXTCC associated with this connection. 





DESCRIPTION 


TRANSPORT_OPEN_CALLBACK performs a callback to the client during 
the connection-open sequence. Transport semantics require a callback, 

as opposed to a simple AST, during the connection-initiation sequence of 
a connect-to-server operation. Because the callback cannot be performed 
in executive mode, TRANSPORT_OPEN_CALLBACK is invoked as a 
user-mode AST to complete this operation. 


If the user accepts the connection, TRANSPORT_OPEN_CALLBACK 
populates the communication queue with transport buffers and initiates 
V/O. If it fails, TRANSPORT_OPEN_CALLBACK generates a message and 
releases the connection resources. 


The TRANSPORT_OPEN_CALLBACK routine is called in user-AST mode. 


See Section 8.3.15 for a sample implementation of the TRANSPORT_ 
OPEN_CALLBACK routine. 


TRANSPORT_READ_AST 


TRANSPORT READ AST 


Read-completion AST routine for the transport’s network channel. Internal to 
specific transport. 





FORMAT 


TRANSPORT_READ_AST idb 





ARGUMENT 


tdb 


VMS usage: record 

type: xtdb 

access: modify 

mechanism: reference 

The XTDB associated with this connection. 





DESCRIPTION 


TRANSPORT_READ_AST is a read-completion AST routine for the 
transport’s network channel. The TRANSPORT_READ_AST routine 
receives connection request notifications only. All other requests from 
clients are sent by means of the connection-specific channel, not the 
transport-specific channel, and do not follow the TRANSPORT_READ_ 
QUEUE to TRANSPORT_READ_AST code path. 


TRANSPORT_READ_AST must allocate and initialize an XTCC, put it on 
the XTDB for this transport, and then call the connection request action 
routine XTDB$A_CONNECT_REQUEST provided by the server. 


The TRANSPORT_READ_AST routine is called in executive mode. 


See Section 8.3.14 for a sample implementation of the TRANSPORT_ 
READ_AST routine. 
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TRANSPORT_READ_QUEUE 


TRANSPORT_READ_ QUEUE 


Initiates an asynchronous connection-accept operation. Internal to specific 








transport. 
FORMAT TRANSPORT_READ_ QUEUE idb 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write 


mechanism: value 


Returns a longword condition value in RO. 





ARGUMENT tdb 


VMS usage: record 

type: xtdb 

access: modify 

mechanism: reference 

The XTDB associated with this connection. 





DESCRIPTION TRANSPORT_READ_QUEUE initiates an asynchronous connection-accept 
operation. 


The XTFT$A_ATTACH_TRANSPORT routine assigns a network channel 
for the transport and then calls TRANSPORT_READ_QUEUE to listen on 
the channel for a connection attempt from a client. 


In the case of the sample transport, the TRANSPORT_READ_QUEUE 
routine assigns a channel for this connection and then does a $QIO read 
operation with function IO$_ACCESS or IO$M_ACCEPT on the transport- 
specific channel created by XTFT$A_ATTACH_TRANSPORT. This $QIO 
performs the following functions: 


e “Listens” on this channel for a $QIO connection request from a client. 


e When a connection request from a client is received, the $QIO gets a 
description of the client node from the client. 


¢ Calls the TRANSPORT_READ_AST routine to accept the connection. 
The transport must accept all valid connection requests; the server 
later decides if it wants to reject a connection from the client. 


The TRANSPORT_READ_QUEJUE routine is called in executive mode. 


See Section 8.3.13 for a sample implementation of the TRANSPORT_ 
READ_QUEUE routine. 
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WRITE_AST 


WRITE_AST 


AST completion routine for transport write operations. Internal to specific 
transport. 











FORMAT WRITE_AST xtcb 
ARGUMENT Xtcb 
VMS usage: record 
type: xtcb 
access: modify 
mechanism: reference 
The XTCB to return to the appropriate free queue. 
DESCRIPTION  WRITE_AST is an AST completion routine for transport write operations. 


WRITE_AST is used by the XTFT$A_WRITE routine to return an XTCB 
to the large or small free queue after a successful write operation and to 
initiate another write operation. 


If the $QIO failed, or the connection is dying, WRITE_AST performs 
failure processing and prevents further operations on this connection. 
Failure processing is dependent upon the type of transport being used. In 
the case of the TCP/IP service provided by the ULTRIX Connection product 
(UCX), a failed I/O attempt to the connection indicates that a connection 
has aborted. When an I/O operation completes and the status indicates 
failure, the routine must perform all logical-link rundown operations, 
including setting the dying bit and error status, completing any process 
waits for input or output, and sending notification to the process that the 
connection has died. 


After WRITE_AST returns the XTCB to the free queue, it attempts to 
remove another XTCB from the head of the output work queue and 
initiate a $QIO write operation. If the queue was empty, WRITE_AST 
clears the write disable flag for this connection by means of the XPORT_ 
OUT_WRITE_ENABLE macro. 


WRITE_AST is invoked in user or executive mode. 


See Section 8.3.4 for a sample implementation of the WRITE_AST routine. 
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XTFT $A_ATTACH_TRANSPORT 


XTFT$A_ATTACH_TRANSPORT 


Performs the transport-specific initialization functions. 





FORMAT 


XTFT$A_ATTACH_TRANSPORT idb 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write 

mechanism: value 


Returns a longword condition value in RO. 





ARGUMENT 


tdb 

VMS usage: record 

type: xtdb 

access: modify 

mechanism: reference 

XTDB structure. This will have been initialized = the caller prior to 
entry. 





DESCRIPTION 


? 
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As described in Section 3.3.2.1, the DECW$XPORT_ATTACH_ 
TRANSPORT routine calls the XTFTS$A._. ATTACH TRANSPORT routine 
to complete the transport-specific initialization. 


XTFT$A_ATTACH_TRANSPORT functions differently depending on what 
calls it. 


If Xlib calls it, XTFT$A_ATTACH_TRANSPORT does only some transport- 
specific initialization because clients attach specific transports when they 
open a connection. 


If the server calls it, as determined by the XTDB XTDB$V_MODE field, 
XTFT$A_ATTACH_TRANSPORT creates a mailbox (if DECnet) and gets . 
a channel to the device by means of $ASSGN. The specific transport uses 
this channel to listen for connection requests from clients; the specific 
transport later assigns a separate channel for each connection. 


XTFT$A_ATTACH_TRANSPORT also indirectly calls the server’s 
connection_request routine to see if the server accepts a connection from 
this client. If the returned status indicates failure, XTFT$A_ATTACH_ 
TRANSPORT deallocates all resources acquired to this point and quits. 


Once the channel is established, XTFT$A_ATTACH_TRANSPORT starts a 
$QIO read (by means of TRANSPORT_READ_QUEUE) on the channel. 


XTFT$A_ATTACH_ TRANSPORT is invoked in user or executive mode. 


See Section 8.3.12 for a sample implementation of the XTFT$A_ATTACH_ 
TRANSPORT routine. 


XTFT$A_CLOSE 


XTFT$A_CLOSE 


Closes a transport connection. 





FORMAT 


XTFT$A_CLOSE _itcc 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write 

mechanism: value 


Returns a longword condition value in RO. 





ARGUMENT 


licc 

VMS usage: record 

type: ixtcc 

access: modify 

mechanism: by reference 
Address of the connection to close. 





DESCRIPTION 


The XTFT$A_CLOSE routine initiates a series of operations that destroy a 
connection and release the data structures associated with the link. 


After XTFT$A_CLOSE is called, the transport user must not refer to 
any structures associated with the connection. The transport begins 
deallocation of all connection resources including, but not limited to, 
channels, XTCC, XTCBs, XTPB, and transport-private data. 


XTFT$A_CLOSE is invoked in executive mode. 


See Section 8.3.9 for a sample implementation of the XTFT$A_CLOSE 
routine. 
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XTFT$A_EXECUTE_FREE 


XTFT$A_EXECUTE_FREE 


Returns an XTCB to a local connection. 





FORMAT 


XTFT$A_EXECUTE_FREE tcc, nullarg, type, 
free_queue 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write 

mechanism: value 


Returns a longword condition value in RO. 





ARGUMENTS 
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tcc 

VMS usage: record 

type: xtcc 

access: modify 

mechanism: by reference 

Address of the XTCC for this connection. 


nullarg 

VMS usage: null_arg 

type: longword (unsigned) 
access: read 


mechanism: value 


Place-holding argument reserved for historical reasons. It is never referred 
to by XTFT$A_EXECUTE_FREE and its contents are unpredictable. 


type 

VMS usage: longword 
type: longword 
access: read 


mechanism: value 
Type of XTCB. Valid types are DECW$C_XPORT_BUFFER_LRP or 
DECW$C_XPORT_BUFFER_SRP. 


free_queue 

VMS usage: array 

type: longword 
access: modify 
mechanism: reference 
Pointer to the free queue. 


XTFT$A_EXECUTE_FREE 





DESCRIPTION 


The XTFT$A_EXECUTE_FREE routine logically returns an XTCB to 
a logical link. The common transport DECW$XPORT_FREE_INPUT_ 
BUFFER invokes XTFT$A_EXECUTE_FREE after it returns an input 
XTCB to a previously empty free queue. 


XTFT$A_EXECUTE_FREE checks to see if input_free operations are 
enabled for this connection and tries to remove the first XTCB. If it 
successfully removes the XTCB, XTFT$A_EXECUTE_FREE initiates a 
$QIO read into it by invoking DECW$$XPORT_FREE_INPUT (which 
invokes XTFT$A_FREE_INPUT_BUFFER). 


The nullarg argument is a placeholder; XTFT$A_EXECUTE_FREE does 
a REMQHI to get the XTCB from the head of the queue. 


XTFT$A_EXECUTE_FREE is invoked in user mode. 


See Section 8.3.6 for a sample implementation of the XTFT$A_EXECUTE_ 
FREE routine. 
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XTFT$A_EXECUTE_WRITE 


XTFT$A_EXECUTE WRITE 


Writes an XTCB to a transport-specific connection. 





FORMAT 


XTFT$A_EXECUTE_WRITE xicc, nullarg, mode 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write 

mechanism: value 


Returns a longword condition value in RO. 





ARGUMENTS 
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Xtcc 

VMS usage: record 

type: xtcc 

access: modify 

mechanism: reference 

Address of the XTCC for this connection. 


nullarg 

VMS usage: null_arg 

type: longword (unsigned) 
access: read 


mechanism: value 
Place-holding argument reserved for historical reasons. 


mode 

VMS usage: longword 
type: longword 
access: read 


mechanism: value 
Modifying flags for the write operation. The valid field is: 


Constant Description 
DECW$M_MODE_NOBLOCK Nonblocking write. If no buffer is available when 


an attempt is made to allocate one, do not block 
but return the status value DECW$_BUFNOTAVL. 


XTFT$A_EXECUTE_WRITE 





DESCRIPTION XTFT$A_EXECUTE_WRITE is invoked to write an XTCB to a transport 
connection. XTFT$A_EXECUTE_WRITE is expected to remove the head 
XTCB from the output work queue and, if the remove was successful, 
initiate a write operation for the XTCB by invoking the common transport 
DECW$$XPORT_WRITE routine. DECW$$XPORT_WRITE then calls 
XTFT$A_WRITE to send the buffer. 


The nullarg argument is a placeholder retained for historical reasons; its 
value is never accessed or relied upon. 


XTFT$A_EXECUTE_WRITE is invoked in user mode. 


See Section 8.3.2 for a sample implementation of the XTFT$A_EXECUTE_ 
WRITE routine. 
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XTFT$A_FREE_INPUT_BUFFER 


XTFT$A_FREE_INPUT_BUFFER 


Starts a read operation on a freed input buffer. 





FORMAT 


XTFT$A_FREE_INPUT_BUFFER itcc, tcb 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write 

mechanism: value 


Returns a longword condition value in RO. 





ARGUMENTS 


itcc 

VMS usage: record 

type: ixtec 

access: modify 

mechanism: by reference 

Address of the connection where communication takes place. 


tcb 


VMS usage: record 

type: xtcb 

access: modify 
mechanism: by reference 
Address of the XTCB to free. 





DESCRIPTION 
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The XTFT$A_FREE_INPUT_BUFFER routine does a $QIO read operation 
for a connection into the provided buffer. If the read $QIO fails, XTFT$A_ 
FREE_INPUT_BUFFER inserts the XTCB on the free queue and sets the 

connection state to dying. 


The transport-common DECW$$XPORT_FREE_INPUT routine calls 
the XTFT$A_FREE_INPUT_BUFFER routine to perform a $QIO read 
operation for the connection. 

Unlike the XTFT$A_EXECUTE_FREE routine, the xteb argument 

is a “real” XTCB and it is assumed that any enable/disable checks, 
performed with the XPORT_IN_FREE_DISABLE macro, have already 
been performed. 


XTFT$A_FREE_INPUT_BUFFER is invoked in executive mode. 


See Section 8.3.7 for a sample implementation of the XTFT$A_FREE_ 
INPUT_BUFFER routine. 


XTFT$A_OPEN 





XTFT$A_OPEN 


Attempts to establish a connection to a server. 





FORMAT 


XTFT$A_OPEN  worksiation, server, itcc 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write 

mechanism: value 


Returns a longword condition value in RO. 





ARGUMENTS 


workstation 

VMS usage: char string 

type: descriptor 

access: read 

mechanism: reference 

Name of the server object passed by descriptor. Contains network address 
and authentication information. The workstation argument is usually a 
node name. 


server 

VMS usage: longword 

type: longword 

access: read 

mechanism: value 

The number of the server to be connected. The server argument is usually 
zero because most workstations run only one server. 


itec 

VMS usage: record 

type: ixtec 

access: modify 

mechanism: reference 

Location of a preallocated IXTCC. This IXTCC has an XTPB (IXTCC$A_ 
TPB and XTCC$A_TPB) that has been initialized. 





DESCRIPTION 


The XTFT$A_OPEN routine tries to connect a client to a server. 


The transport-common DECW$XPORT_OPEN routine attempts to locate 
a transport with a name matching that passed in its xportnam argument 
(for example “DECNET”). If a matching transport is found, the XTFT$A_ 
OPEN routine is called with the server and workstation arguments and an 
IXTCC that has been partially initialized. 


XTFT$A_OPEN 
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XTFT$A_OPEN is responsible for allocating and initializing the XTCC and 
all necessary XTCBs, populating the XTCQ with the XTCBs, and initiating 
I/O on the connection. Parameters that would affect these operations are 
found in the XTPB attached to the IXTCC by means of the IXTCC$A_TPB 
field. 


XTFT$A_OPEN is invoked in executive mode. 


See Section 8.3.11 for a sample implementation of the XTFT$A_OPEN 
routine. 


XTFT$A_RUNDOWN 


XTFT$A_RUNDOWN 


Performs the transport-specific rundown functions required during image 








rundown. 
‘FORMAT XTFT$A_RUNDOWN idb 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write 


mechanism: value 


Returns a longword condition value in RO. 





ARGUMENT tdb 
VMS usage: record 
type: xtdb 
access: modify 
mechanism: reference 
XTDB structure. The XTDB is initialized by the common transport before 
XTFT$A_RUNDOWN is called. 





DESCRIPTION XTFT$A_RUNDOWN is invoked by the common transport when the 
image in which the transport is running exits. The transport’s rundown 
procedure must release any resources that might survive the image exit. 
ASTs are disabled while XTFT$A_RUNDOWN is executing. 


XTFT$A_RUNDOWN is invoked in executive mode. 


See Section 8.3.18 for a sample implementation of the XTFT$A_ 
RUNDOWN routine. 
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XTFT$A_WRITE 


XTFT$A_WRITE 


Writes an XTCB buffer from the common transport to a transport-specific 
connection. 











FORMAT XTFT$A_WRITE _itcc, tcb, mode 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write 

mechanism: value 

Returns a longword condition value in RO. 
ARGUMENTS __ itcc 

VMS usage: record 

type: xtcc 

access: modify 

mechanism: reference 

Address of the IXTCC for this connection. 

tcb 

VMS usage: record 

type: xtcb 

access: modify 

mechanism: reference 

Address of the XTCB to write to the transport-specific connection. 

mode 

VMS usage: longword 

type: longword 

access: read 

mechanism: value 


Modifying flags for the write operation. The valid field is: 


Constant 


DECW$M_MODE_NOBLOCK 


Description 


Nonblocking write. If no buffer is available when 
an attempt is made to allocate one, do not block 
but return the status value DECW$_BUFNOTAVL. 


XTFT$A_WRITE 





DESCRIPTION 


The XTFT$A_WRITE routine is invoked to write the data in an XTCB, 
possibly by means of $QIO, to a transport connection associated with the 
XTCC. If there is nothing to write, that is, the XTCB is empty, XTFT$A_ 
WRITE inserts the XTCB on the appropriate (small or large) output free 
queue. 


If the $QIO write operation fails, XTFT$A_WRITE puts the XTCB back at 
the head of the output work queue and sets the connection status to dying. 


Unlike XTFT$A_EXECUTE_WRITE, the XTCB parameter in the 
argument list is significant and is the address of an XTCB, not an element 
of any queue, whose data is to be written to a connection. 


The XTFT$A_WRITE routine is called in executive mode. 


See Section 8.3.3 for a sample implementation of the XTFT$A_WRITE 
routine. 
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XTFT$A_WRITE_USER 


XTFT$A_ WRITE USER 


Attempts to write a ‘buffer in the user’s address space to a transport-specific 








connection. 
FORMAT XTFT$A_WRITE_USER __iicc, buffer, mode 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write 


mechanism: value 


Returns a longword condition value in RO. 





ARGUMENTS __ itcc 
VMS usage: record 
type: ixtcc 
access: modify 
mechanism: reference 
Address of the IXTCC data structure that identifies the connection. 


buffer 

VMS usage: char string 
type: char string 
access: read 


mechanism: descriptor 
A buffer in the user’s address space that contains data to write to the 


connection. 

mode 

VMS usage: longword 
type: longword 
access: read 


mechanism: value 
Modifying flags for the write operation. The valid field is: 


Constant Description 
DECW$M_MODE_NOBLOCK Nonblocking write. If no buffer is available when 


an attempt is made to allocate one, do not block 
but return the status value DECW$_BUFNOTAVL. 


XTFT$A_WRITE_USER 





DESCRIPTION 


The XTFT$A_WRITE_USER routine attempts to write a buffer in the 
user’s address space to a transport connection. The purpose of this 
interface is to avoid a data copy into XTCBs when the caller has a large, 
contiguous block of data to be written to a connection, such as when 
sending image data between client and server. 


There are two methods for implementing this routine. The first is to wait 
for the output work queue to become empty and then perform the I/O 
operation on the user’s buffer, typically by means of a $QIO. The other 
method is to invoke the common transport’s DECW$XPORT_COPY_AND_ 
WRITE routine for the buffer arguments. It is strongly recommended that 
transports use the DECW$XPORT_COPY_AND_ WRITE routine. 


XTFT$A_WRITE_USER is called in user mode. 


See Section 8.3.5 for a sample implementation of the XTFT$A_WRITE_ 
USER routine. 
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Transport Support Macros 





This chapter describes the support macros that you can use if you write 
your own transport-specific component. These routines are provided for 
your convenience; there is no requirement that you use them, but you 
must implement similar functions. 


The transport support macros are located in the file 
SYS$LIBRARY:DECW$XPORTMAC.R382. 


The transport support macros are listed in Table 7-1. 


Table 7-1 Transport Support Macros 


Routine 


XPORT_IN_NOTIFY_SET 
XPORT_IN_NOTIFY_CLEAR 
XPORT_IN_NOTIFY_WAIT 
XPORT_IN_NOTIFY_SEND 


XPORT_OUT_NOTIFY_SET 
XPORT_OUT_NOTIFY_CLEAR 


XPORT_OUT_NOTIFY_WAIT 
XPORT_OUT_NOTIFY_SEND 


XPORT_XTCB_FILLED 
XPORT_XTCB_TOTAL 


XPORT_XTCB_FREE 


XPORT_WRITE_WAIT 
XPORT_WRITE_UNWAIT 
XPORT_ABORT_SEND 


XPORT_OUT_WRITE_ENABLE 
XPORT_OUT_WRITE_DISABLE 
XPORT_OUT_STATE_SRP 


XPORT_OUT_STATE_LRP 


Function 


Requests input notification. 
Clears a request-for-input notification. 
Initiates a wait-for-input notification. 


Sends notice that an input operation has 
completed. 


Sends notice that output notification is required. 


Sends notice that output notification is no longer 
required. 


Waits for output notification. 


Sends notice that an output operation has 
completed. 


Returns the number of data bytes in an XTCB. 


Determines the total number of bytes in the data 
area of an XTCB. 


Determines the number of unused bytes in the 
data area of an XTCB. 


Waits for the output work queue to empty. 
Reenables output work queue write operations. 


Declares a user-mode AST to the process 
indicating that the connection has died. 


Clears the write disable flag. 
Sets the write disable flag. 


Marks a switch to the use of SRPs for output 
and returns true (1) if an LRP was being used. 


Marks a switch to the use of LRPs for output 
and returns true (1) if an SRP was being used. 


(continued on next page) 
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Table 7-1 (Cont.) Transport Support Macros 


Routine 


XPORT_IN_STATE_SRP 
XPORT_IN_STATE_LRP 


XPORT_IN_FREE_ENABLE 


XPORT_IN_FREE_DISABLE 


VALIDATE_XTCC 
VALIDATE_USERW 
VALIDATE_USER 


Function 


Marks a switch to the use of SRPs for input and 
returns true (1) if an LRP was being used. 


Marks a switch to the use of LRPs for input and 
returns true (1) if an SRP was being used. 


Clears the free disable flag for this connection 
type of queue and returns true (1) if it was clear 
or false (0) if it was set. 


Sets the free disable flag for this connection 
and type of queue and returns true (1) if it was 
set or false (0) if it was clear. 


Validates an XTCC and returns the IXTCC. 
Checks user buffer for write access. 
Checks user buffer for read access. 


XPORT_IN_NOTIFY_SET 


XPORT_IN NOTIFY SET 


Requests input notification. 





FORMAT XPORT_IN_NOTIFY_SET xicc 





ARGUMENTS-  Xicc 
VMS usage: record 
type: xtcc 
access: modify 
mechanism: value 
The XTCC of the connection for which input notification is requested. 





DESCRIPTION The XPORT_IN_NOTIFY_SET macro clears the waiting-for-input I/O 
status block (IOSB) field of the XTCC and sets the XTCC$L_IWQ_FLAG 
bit to indicate that the transport user wants to be notified when input is 
delivered to the input work queue. 


XPORT_IN_NOTIFY_CLEAR 


XPORT_IN NOTIFY CLEAR 


Clears a request-for-input notification. 





FORMAT XPORT_IN NOTIFY CLEAR xtcc 





ARGUMENTS '-  xicc 
VMS usage: record 
type: xtcc 
access: modify 
mechanism: reference 
The XTCC of the connection for which to cancel input notification. 





DESCRIPTION The XPORT_IN_NOTIFY_CLEAR macro clears the XTCC$L_IWQ_FLAG 
bit to indicate that the transport user no longer wants to be notified when 
input is delivered to the input work queue. 


XPORT_IN_NOTIFY_WAIT 


XPORT_IN_NOTIFY_WAIT 


Initiates a wait-for-input notification 





FORMAT XPORT_IN_NOTIFY_WAIT  xtcc, xtpb 





ARGUMENTS~= Xicc 
VMS usage: record 
type: xtcc 
access: modify 
mechanism: reference 
The XTCC of the connection for which to wait for input notification. 


xtpb 

VMS usage: record 
type: xtpb 
access: modify 


mechanism: reference 
The XTPB of the connection for which to wait for input notification. 





DESCRIPTION The XPORT_IN_NOTIFY_WAIT macro calls the $SYNCH system service 
to suspend a process until input notification is set. The service is 
satisfied when the XTPB$W_IN_EFN flag is set and the lower word of 
the XTCC$W_IN_IOSB is made nonzero, as performed by the XPORT_IN_ 
NOTIFY_SEND macro. 


XPORT_IN_NOTIFY SEND 


XPORT_IN NOTIFY SEND 


Sends notice that an input operation has completed. 





FORMAT XPORT_IN_NOTIFY_SEND xicc, xtpb 





ARGUMENTS~=  Xicc 
VMS usage: record 
type: xtcc 
access: modify 
mechanism: reference 
The XTCC of the connection for which to send input notification. 


xtpb 

VMS usage: record 
type: xtpb 
access: modify 


mechanism: reference 
The XTPB of the connection for which to send input notification. 





DESCRIPTION The XPORT_IN_NOTIFY_SEND macro conditionally performs the 
operations that inform a process that an input operation has completed. 
These operations consist of sending a user-mode AST to the process in the 
case where the XTPB$A_I_NOTIFY_RTNADR field points to a procedure 
to call for input notification, or of code that completes the $SYNCH system 
service call performed by the XPORT_IN_NOTIFY_WAIT macro. 


XPORT_IN_NOTIFY_SEND sends the AST only if the previous AST 
(identified by the XTCC$V_IN_AST_IN_PROG field) has been delivered, 
that is, the field was clear. This prevents EXQUOTA errors due to 
excessive use of ASTs. 


( 


XPORT_OUT_NOTIFY_SET 


XPORT OUT NOTIFY SET 


Sends notice that output notification is required. 





FORMAT 


XPORT_OUT_NOTIFY_SET xicc, type 





ARGUMENTS 


xtcc 

VMS usage: record 

type: xtcc 

access: modify 

mechanism: reference 

The XTCC of the connection for which you want to receive output 
notification. 


type 

VMS usage: longword 

type: longword 

access: read 

mechanism: value 

The type of output free queue you are interested in. Valid types are 
DECW$C_XPORT_BUFFER_SRP and DECW$C_XPORT_BUFFER_LRP. 





DESCRIPTION 


The XPORT_OUT_NOTIFY_SET macro clears the waiting-for-output I/O 
status block (IOSB) field of the XTCC and sets the XTCC$L_OFSQ_FLAG 
or XTCC$L_OFLQ_FLAG bit to indicate that you are waiting for the 
output free queue to become empty. 


XPORT_OUT_NOTIFY_CLEAR 


XPORT OUT NOTIFY CLEAR 


Sends notice that output notification is no longer required. 





FORMAT XPORT_OUT_NOTIFY_CLEAR xtcc, type 


ARGUMENTS~ Xicc 
VMS usage: record 
type: xtec 
access: modify 
mechanism: reference 
The XTCC of the connection for which you want to cancel output 
notification. 


type 

VMS usage: longword 
type: longword 
access: read 
mechanism: value 


The type of output free queue you are no longer interested in. Valid types 
are DECW$C_XPORT_BUFFER_SRP and DECW$C_XPORT_BUFFER_ 
LRP. 





DESCRIPTION The XPORT_OUT_NOTIFY_CLEAR macro clears the XTCC$L_OFSQ_ 
FLAG or XTCC$L_OFLQ_FLAG bit to indicate that you do not want to 
receive output notification. The XPORT_OUT_NOTIFY_CLEAR macro 
reverses the effect of the XPORT_OUT_NOTIFY_SET macro. 


XPORT_OUT_NOTIFY_WAIT 


XPORT OUT NOTIFY WAIT 


Waits for output notification. 





FORMAT 


XPORT_OUT NOTIFY WAIT  xtcc, xtob 





ARGUMENTS 


xtcc 

VMS usage: record 

type: xtcc 

access: modify 

mechanism: reference 

The XTCC of the connection for which you want to wait for output 
notification. 


xtpb 

VMS usage: record 

type: xtpb 

access: modify 

mechanism: reference 

The XTPB of the connection for which you want to wait for output 
notification. 





DESCRIPTION 


The XPORT_IN_NOTIFY_WAIT macro calls the $SYNCH system service 
to suspend a process until output notification is set. The service is 
satisfied when the XTPB$W_ON_EFN flag is set and the lower word 

of the XTCC$W_ON_IOSB field is made nonzero, as performed by the 
XPORT_OUT_NOTIFY_SEND macro. 


XPORT_OUT_NOTIFY_SEND 


XPORT OUT NOTIFY SEND 


Sends notice that an output operation has completed. 





FORMAT 


XPORT_OUT_NOTIFY_SEND  xtcc, xtob, type 





ARGUMENTS 


Xtcc 

VMS usage: record 

type: xtcc 

access: modify 

mechanism: reference 

The XTCC of the connection for which you want to send output 
notification. 


xtpb 

VMS usage: record 

type: xtpb 

access: modify 

mechanism: reference 

The XTPB of the connection for which you want to send output notification. 


type 

VMS usage: longword 
type: longword 
access: read 
mechanism: value 


The type of output free queue you are interested in. Valid types are 
DECW$C_XPORT_BUFFER_SRP and DECW$C_XPORT_BUFFER_LRP. 





DESCRIPTION 
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The XPORT_OUT_NOTIFY_SEND macro conditionally performs the 
operations that inform a process that an output operation has completed. 
These operations consist of sending a user-mode AST to the process in the 
case where the XTPB$A_O_NOTIFY_RTNADR field points to a procedure 
to call for output notification, or of code that completes the $SYNCH 
system service call performed by the XPORT_OUT_NOTIFY_WAIT macro. 


XPORT_XTCB_FILLED 


XPORT_XTCB_ FILLED 


Returns the number of data bytes in an XTCB. 





FORMAT XPORT_XTCB FILLED xtcb 





ARGUMENTS-~  xtcb 
VMS usage: record 
type: xtcb 
access: modify 
mechanism: reference 
The XTCB for which you want to return the number of data bytes in an 
XTCB. 





DESCRIPTION The XPORT_XTCB_FILLED macro returns the number of data bytes in 
an XTCB 


7-11 


XPORT_XTCB_TOTAL 


XPORT_XTCB_TOTAL 


Determines the total number of bytes in the data area of an XTCB. 





FORMAT XPORT_XTCB_TOTAL xicb 


ARGUMENTS xicb 
VMS usage: record 
type: xtcb 
access: modify 
mechanism: reference 
The XTCB for which you want to determine the total number of bytes in 
the data area of an XTCB. 





DESCRIPTION The XPORT_XTCB_TOTAL macro determines the total number of bytes in 
the data area of an XTCB. 


XPORT_XTCB_FREE 


XPORT_XTCB_FREE 


Determines the number of unused bytes in the data area of an XTCB. 





FORMAT XPORT_XTCB_FREE xicb 





ARGUMENTS '- Xicb 
VMS usage: record 
type: xtcb 
access: modify 
mechanism: reference 
The XTCB for which you want to determine the number of unused bytes 
in the data area of an XTCB. 





DESCRIPTION The XPORT_XTCB_FREE macro determines the number of unused bytes 
in the data area of an XTCB. 
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XPORT_WRITE_WAIT 





XPORT_WRITE_WAIT 


Waits for the output work queue to empty. 





FORMAT XPORT_WRITE_WAIT xicc, xtpb 





ARGUMENTS-~ Xicc 
VMS usage: record 
type: xtcc 
access: modify 
mechanism: reference 
The XTCC for the connection on which you want to wait. 


xtpb 

VMS usage: record 
type: xtpb 
access: modify 


mechanism: reference 
The XTPB for the connection on which you want to wait. 





DESCRIPTION The XPORT_WRITE_WAIT macro performs a $SYNCH system service to 
wait for the output work queue to empty. XPORT_WRITE_WAIT is similar 
to XPORT_OUT_NOTIFY_WAIT, but uses the XTCC$W_OW_IOSB field. 
Also, because there are no equivalents to the XPORT_OUT_NOTIFY_SET 
and XPORT_OUT_NOTIFY_CLEAR macros, you must manually clear the 
XTCC$W_OW_IOSB field, or set or clear the XTCC$V_WAIT_ON_WRITE 
bit. 


XPORT_WRITE_UNWAIT 


XPORT WRITE _UNWAIT 


Reenables output work queue write operations. 





FORMAT XPORT_WRITE_UNWAIT <xicc, xtpb 





ARGUMENTS -~ Xicc 
VMS usage: record 
type: xtcc 
access: modify 
mechanism: reference 
The XTCC for which you no longer want to wait. 


xtpb 

VMS usage: record 
type: xtpb 
access: modify 


mechanism: reference 
The XTPB for which you no longer want to wait. 





DESCRIPTION The XPORT_WRITE_UNWAIT macro cancels the wait on the output work 
queue initiated by XPORT_WRITE_WAIT. 
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XPORT_ABORT_SEND 


XPORT_ ABORT SEND 


Declares a user-mode AST to the process indicating that the connection has 
aborted. 





FORMAT XPORT_ABORT_SEND xidb, xtcc 





ARGUMENTS '-  Xxidb 
VMS usage: record 
type: xtdb 
access: modify 
mechanism: reference 
The XTDB for which you want to abort the connection. 


xtcc 

VMS usage: record 
type: xtcc 
access: modify 


mechanism: reference 
The XTCC for which you want to abort the connection. 





DESCRIPTION The XPORT_ABORT_SEND macro declares a user-mode AST to the user- 
provided connection-abort notification process, identified by the XTDB$A_ 
CONNECT_ABORT field, indicating that the connection has died. 


XPORT_ABORT_SEND is called as part of the abort notification. 
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XPORT_OUT_WRITE_ENABLE 


XPORT OUT WRITE ENABLE 


Clears the write disable flag. 





FORMAT 


XPORT_OUT_WRITE_ENABLE xicc 





RETURNS 


VMS usage: longword 
type: longword 
access: write 
mechanism: value 


Returns true (1) if the XTCC$L_OWQ_FLAG field was clear, that is, if 
write operations were already enabled, or false (0) if it was set. 





ARGUMENTS 


Xtcc | 

VMS usage: record 

type: xtcc 

access: modify 

mechanism: reference 

The XTCC for which you want to enable write operations. 





DESCRIPTION The XPORT_OUT_WRITE_ENABLE macro clears the write disable flag 


for this connection and returns true (1) if it was clear or false (0) if it was 
set. 


XPORT_OUT_WRITE_DISABLE 


XPORT_OUT WRITE DISABLE 


Sets the write disable flag. 








FORMAT XPORT_OUT WRITE_DISABLE xtcc 
RETURNS VMS usage: longword 

type: longword 

access: write 


mechanism: value 


Returns true (1) if the XTCC$L_OWQ_FLAG was set, that is, if write 
operations were already disabled, or false (0) if it was clear. 





ARGUMENTS-~ Xicc 
VMS usage: record 
type: xtcc 
access: modify 
mechanism: reference 
The XTCC for which you want to disable write operations. 





DESCRIPTION The XPORT_OUT_WRITE_DISABLE macro sets the write disable flag for 
this connection and returns true (1) if it was set or false (0) if it was clear. 


XPORT_OUT_STATE_SRP 


XPORT OUT STATE SRP 


Marks a switch to the use of SRPs for output and returns true (1) if an LRP 
was being used. 





FORMAT 


XPORT_OUT_STATE_SRP xicc 





RETURNS 


VMS usage: longword 
type: longword 
access: write 
mechanism: value 


Returns true (1) if an LRP was being used. 





ARGUMENTS 


xtec 

VMS usage: record 

type: xtcc 

access: modify 

mechanism: reference 

The XTCC for which you want to test and set the state. 





DESCRIPTION 


The XPORT_OUT_STATE_SRP macro tests to see if the XTCC$V_LRP_ 
ON_OUTPUT bit was set, and then clears it. XPORT_OUT_STATE_SRP 
marks a switch to the use of SRPs for output and returns true (1) if an 
LRP was being used. 


XPORT_OUT_STATE_LRP 


XPORT_OUT_STATE_LRP 


Marks a switch to the use of LRPs for output and returns true (1) if an SRP 
was being used. 








FORMAT XPORT_OUT_STATE_LRP xicc 
RETURNS VMS usage: longword 

type: longword 

access: write 


mechanism: value 


Returns true (1) if an SRP was being used. 





ARGUMENTS~ Xicc 
VMS usage: record 
type: xtcc 
access: modify 
mechanism: reference 
The XTCC for which you want to test and set the state. 





DESCRIPTION The XPORT_OUT_STATE_LRP macro tests to see if the XTCC$V_LRP_ 
ON_OUTPUT bit was clear, and then sets it. XPORT_OUT_STATE_SRP 
marks a switch to the use of LRPs for output and returns true (1) if an 
SRP was being used. 


XPORT_IN_STATE_SRP 


XPORT_IN STATE _SRP 


Marks a switch to the use of SRPs for input and returns true (1) if an LRP was 
being used. 





FORMAT 


XPORT_IN_STATE_SRP xicc 





RETURNS 


VMS usage: longword 
type: longword 
access: write 
mechanism: value 


Returns true (1) if an LRP was being used. 





ARGUMENTS 


xtcc 

VMS usage: record 

type: xtcc 

access: modify 

mechanism: reference 

The XTCC for which you want to test and set the state. 





DESCRIPTION 


The XPORT_IN_STATE_SRP macro tests to see if the XTCC$V_LRP_ON_ 
INPUT bit was set, and then clears it. XPORT_IN_STATE_SRP marks 

a switch to the use of SRPs for input and returns true (1) if an LRP was 
being used. 
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XPORT_IN_STATE_LRP 


XPORT_IN STATE _LRP 


Marks a switch to the use of LRPs for input and returns true (1) if an SRP was 








being used. 
FORMAT XPORT_IN_STATE_LRP <xicc 
RETURNS VMS usage: longword 

type: longword 

access: write 


mechanism: value 


Returns true (1) if an SRP was being used. 





ARGUMENTS’ Xicc 
VMS usage: record 
type: xtcc 
access: modify 
mechanism: reference 
The XTCC for which you want to test and set the state. 





DESCRIPTION The XPORT_IN_STATE_LRP macro tests to see if the XTCC$V_LRP_ON_ 
INPUT bit was clear, and then sets it. XPORT_IN_STATE_SRP marks a 
switch to the use of LRPs for input and returns true (1) if an SRP was 
being used. 


XPORT_IN_FREE_ENABLE 


XPORT_IN_ FREE ENABLE 


Clears the free disable flag for this connection type of queue and returns (1) if 
it was clear or (0) if it was set. 





FORMAT 


XPORT_IN FREE ENABLE xicc, type 





RETURNS 


VMS usage: longword 
type: longword 
access: write 
mechanism: value 


Returns true (1) if the free disable flag was clear, that is, input operations 
were already enabled, or false (0) if it was set. 





ARGUMENTS 


xXtcc 

VMS usage: record 

type: xtcc 

access: modify 

mechanism: reference 

The XTCC for which you want to clear the disable flag. 


type 

VMS usage: longword 

type: longword 

access: read 

mechanism: value 

The type of buffer for which to clear the disable flag. Valid types are 
DECW$XPORT_BUFFER_SRP and DECW$XPORT_BUFFER_LRP. 





DESCRIPTION 


The XPORT_IN_FREE_ENABLE macro tests the XTCC$L_IFSQ_FLAG 
flag or the XTCC$L_IFLQ_FLAG flag (depending on the type argument) 
to see if it is clear, and then clears it. XPORT_IN_FREE_ENABLE returns 
true (1) if the free disable flag was clear or false (0) if it was set. 


XPORT_IN_FREE_DISABLE 





XPORT_IN FREE DISABLE 


Sets the free disable flag for this connection and type of queue and returns 
(1) if it was set or (0) if clear. 








FORMAT XPORT_IN_FREE_DISABLE x icc, type 
RETURNS VMS usage: longword 

type: longword 

access: write 


mechanism: value 


Returns true (1) if the free disable flag was set, that is, free input 
operations were already disabled, or false (0) if it was clear. 





ARGUMENTS ~  Xicc 
VMS usage: record 
type: xtec 
access: modify 
mechanism: reference 
The XTCC for which you want to set the disable flag. 


type 

VMS usage: longword 
type: longword 
access: read 


mechanism: value 
The type of buffer for which to set the disable flag. Valid types are 
DECW$XPORT_BUFFER_SRP and DECW$XPORT_BUFFER_LRP. 





DESCRIPTION The XPORT_IN_FREE_ENABLE macro tests the XTCC$L_IFSQ_FLAG 
flag or the XTCC$L_IFLQ_FLAG flag (depending on the type argument) 
to see if it is set, and then sets it. XPORT_IN_FREE_ENABLE returns 
true (1) if the free disable flag was set or false (0) if it was clear. 


VALIDATE_XTCC 


VALIDATE_XTCC 


Validates an XTCC and returns the IXTCC. 

















FORMAT status_return=VALIDATE_XTCC  xtcc, ixtcc 

RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write 
mechanism: value 
Returns a longword condition value to RO. Possible condition values are 
listed under Condition Values Returned. 

ARGUMENTS '-  Xicc 
VMS usage: record 
type: xtcc 
access: modify 
mechanism: reference 
The XTCC that you want to validate. 
ixtcc 
VMS usage: record 
type: ixtec 
access: modify 
mechanism: reference 
The previously registered IXTCC address is returned to this argument. 
Valid only if SS$_NORMAL is returned. 

DESCRIPTION The VALIDATE_XTCC macro calls the transport-common DECW$XPORT_ 
VALIDATE_STRUCT_JSB routine to validate an XTCC. If the XTCC ID 
is known and is valid, VALIDATE_XTCC returns the previously registered 
address of the IXTCC data structure in the ixtce argument. 
VALIDATE_XTCC is called only by the transport-common component. 

CONDITION 
SS$_ACCVIO The XTCC is not user-readable. 

VALUES 

RETURNED SS$_NORMAL Routine successfully completed. 

SS$_BADPARAM Bad parameter. Either the XTCC$B_SUBTYPE field 


is not equal to the constant DECW$C_DYN_XTCC, or 
the IXTCC$A_TCC field does not point to this XTCC. 


Any DECW$XPORT_VALIDATE_STRUCT_JSB condition value. 
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VALIDATE_USERW 


VALIDATE_USERW 


Checks a user buffer for write access. 








FORMAT status_return=VALIDATE_USERW _ bufadr, buflen 
RETURNS VMS usage: cond_value 

type: longword (unsigned) 

access: write 


mechanism: value 


Returns a longword condition value to RO. Possible condition values are 
listed under Condition Values Returned. 





ARGUMENTS _ bufadr 
VMS usage: record 
type: buffer 
access: modify 
mechanism: reference 
The address of the buffer that you want to check for write access. 


buflen 

VMS usage: longword 
type: longword 
access: read 


mechanism: value 
The length of the buffer that you want to check for write access. 





DESCRIPTION The VALIDATE_USERW macro checks the user-supplied buffer for write 
access and returns a status. 


VALIDATE_USERW is called only by the transport-common component. 





CONDITION 

VALUES SS$_NORMAL Routine successfully completed. The buffer is user- 
writable. 

RETURNED SS$_ACCVIO The buffer is not user-writable. 
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VALIDATE_USER 


VALIDATE_USER 


Checks a user buffer for read access. 








FORMAT Status_return=VALIDATE_USER _ bufadr, buflen 
RETURNS VMS usage: cond_value 
, type: longword (unsigned) 
access: write 


mechanism: value 


Returns a longword condition value to RO. Possible condition values are 
listed under Condition Values Returned. 





ARGUMENTS _ bufadr 
VMS usage: record 
type: buffer 
access: modify 
mechanism: reference 
The address of the buffer that you want to check for read access. 


buflen 

VMS usage: longword 
type: longword 
access: read 


mechanism: value 
The length of the buffer that you want to check for read access. 





DESCRIPTION The VALIDATE_USERW macro checks the user-supplied buffer for read 
access and returns a status. 


VALIDATE_USER is called only by the transport-common component. 





CONDITION 

VALUES SS$_NORMAL Routine successfully completed. The buffer is user- 
readable. 

RETURNED SS$_ACCVIO The buffer is not user-readable. 
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8 Writing Your Own Transport 


8.1 


Note: 


Where to Begin 


This chapter describes the sample transport layer provided in 
DECW$EXAMPLES:XPORT_EXAMPLE.B32. The chapter includes a 
sample BLISS-32 code example for each of the transport-specific routines 
that you must write. This chapter also includes an example of how to 
compile and link the routines as a shareable image in the DECwindows 
environment. 


The code examples collectively describe a TCP/IP transport for : 
DECwindows layered on the ULTRIX Connection product (UCX), the 
implementation of TCP/IP for VMS. Your own implementation of the 
transport-specific routines may be different depending on the lower-level 
transport on which you are building. 


This chapter describes how to write the transport-specific routines 
only. Modifications to the existing transport-common routines are 
not recommended or supported. 





Depending upon your implementation, you will probably find that the 
routines that initialize a transport and establish a connection require the 
most modification. The following routines are included in this group: 


e XTFT$A_OPEN (client side) 
¢ XTFT$A_ATTACH TRANSPORT (server side) 
e TRANSPORT_READ_AST (server side) 


You may also find that routines that primarily insert and remove buffers 
from the queues, such as XTFT$A_EXECUTE_FREE, can be used with 
minimal changes. 


The sample transport layer described in this chapter uses the $QIO 
/AST completion interface. If the lower-level transport on which you 
are building uses the $QIO/AST completion interface, you should check 
the $QIO function codes to make sure that they are applicable in your 
implementation. 


If the lower-level transport on which you are building does not use the 
$QIO/AST completion interface and instead waits for read operations to 
complete, the server may spend a substantial amount of time waiting. 
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8.1.1. Identifying the Transport-Specific Shareable Image 


After you write your own transport-specific layer, you must make it known 
to the transport-common layer as follows: 


¢ Make sure that the transfer vector to DECW$TRANSPORT _INIT is in 
the first cluster of the transport-specific shareable image, as described 
in Section 8.2 and Section 8.3.19. 


¢ Make sure your transport-specific shareable image is in the form 
SYS$SHARE:DECW_TRANSPORT_transport_name.EXE. When 
called by either Xlib or the server, DECW$XPORT_ATTACH_ 
TRANSPORT attempts to locate and activate an image with a name in 
this form. 


Note: Because the common transport uses only executive-mode 
logical names, the logical name SYS$SHARE cannot be 
redefined. 


As described in Section 3.3.1.2, transport names 

that do not contain a “$” character are reserved 

for third-party and customer transport images. 

These transport names must be in the form 
SYS$SHARE:DECW_TRANSPORT_transport_name.EXE. 


¢ Copy SYS$SMANAGER:DECW$PRIVATE_SERVER_ 
SETUP.TEMPLATE to *.COM and modify the DECW$SERVER_ 
TRANSPORTS symbolic name to include your transport. For 
example, DECW$SERVER_TRANSPORTS could translate to 
“DECNET,LOCAL,TCPIP,FOO”. 


The server uses the logical name DECW$SERVER_TRANSPORTS 
to determine which transports to attach and initialize and calls the 
DECW$XPORT_ATTACH_TRANSPORT routine for each transport 
identified by the logical name. The transport_name argument 
specifies the transport, such as “FOO”. 


8.2 Compiling and Linking Options for the Transport 


The DECW$EXAMPLES:DEMO_BUILD.COM procedure supplied with 
the DECwindows kit builds the VMS DECwindows example programs, 
including the sample TCP/IP transport layer described in this chapter. 
You can refer to this procedure for suggestions on compiling and linking a 
transport layer in the DECwindows environment. 


Example 8-1 shows the transport-specific portion of the DEMO_ 
BUILD.COM procedure. 
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Example 8-1 DEMO_BUILD.COM Procedure 





MAA MNNANUNUNUHUAUHNUNNH 


xport_example, - 
xport_example_queue, - 
xport_example xfer, - 
sysS$input/opt 
gsmatch=lequal,12,12 


! If Bliss and UCX are installed on the system and DECwindows is installed 
! with the common transport shareable image and Bliss programming support, 
! then compile and link the example transport. 

! 


if f$search("sys$library:ucx$inetdef.r32") .eqs. "" then goto do_fortran 

if f$search ("sys$share:decw$transport_common.exe") .eqs. "" then goto do fortran 
define/nolog src$ decwSexamples 

bliss decwSexamples:xport_example 

macro decwSexamples:xport_example_ queue 

macro decwSexamples:xport_example xfer 

link/share=decwStransport_example.exe - 


@ cluster=transfer cluster,,, 
collect=transfer cluster, $transfer$ 


6 protect=yes 
cluster=own_cluster,,, 


collect=own_cluster, $own$ 


protect=no 


cluster=code_cluster,,, 


collect=code_ cluster, $code$ 
sys$share:decw$transport_common/shareable 


The DECW$EXAMPLES:XPORT_EXAMPLE_QUEUE.MAR module 
provides emulations of the REMQxI and INSQxI instructions that 
probe the memory occupied by a queue entry to see if it has user-mode 
write access. See Section 3.2.4 for more information. 


The DECW$EXAMPLES:XPORT_EXAMPLE_XFER.MAR module 
generates transfer vectors for the sample transport. 


Link the transport-specific code as a VMS shareable image that can be 
accessed by the transport-common component. 


Prevent image activation of incompatible transport versions. 


Create a cluster for the transfer vector and place the named program 
section, in this case $transfer$, in it. The $transfer$ program section 
points to the DECW$TRANSPORT_INIT routine, as described in 
Section 8.3.19. The transfer vector must be at the beginning of the 
image (in the first cluster) or the transport common will not activate 
it. 


OWN variables are protected from user-mode writing. 
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8.3 Sample TCP/IP Transport Layer Implementation 


The code examples in this section implement a sample TCP/IP 
DECwindows transport layer. 


8.3.1. TCP/IP Transport Layer Setup 


Example 8-2 shows module and data structure declarations, macro and 
literal definitions, and external definitions that are used in the TCP/IP 
implementation. 


Example 8-2 TCP/IP Transport Layer Setup 





STITLE ‘'XPORT EXAMPLE - Example TCP/IP Communication Library’ 
MODULE XPORT_EXAMPLE ( 
IDENT = ’V1.0’, 
ADDRESSING MODE (EXTERNAL = GENERAL, 
NONEXTERNAL = WORD RELATIVE ) 
) = 
BEGIN 


LIBRARY ’SYSSLIBRARY:STARLET’ ; 

REQUIRE ’SYSSLIBRARY:UCXSINETDEF.R32’ ; 
REQUIRE ’SRC$:XPORTEXAMPLEDEF.R32’ ; 
REQUIRE ’SYS$LIBRARY:DECWSXPORTMAC.R32’ ; 
REQUIRE ’ SYS$LIBRARY : DECWSXPORTMSG.R32’ 


e@ 
PSECT 
PLIT = SCODE$ (PIC,SHARE) , 
CODE = SCODES (PIC,SHARE) , 
OWN = SOWNS (PIC,NOSHARE) , 
GLOBAL = SOWNS (PIC,NOSHARE) ; 


© FoRWARD ROUTINE 
DECWSS$TCPIP_EXECUTE WRITE, 
DECWSS$TCPIP_WRITE, 
write _ast : NOVALUE, 
DECWS$TCPIP_WRITE_USER, 
DECWSS$TCPIP_EXECUTE_FREE, 
DECWSSTCPIP_FREE_INPUT_ BUFFER, 
free_input_ast : NOVALUE, 
DECWS$TCPIP_ATTACH_TRANSPORT, 
DECWSS$TCPIP_CLOSE, 
close_and_deallocate_ast : NOVALUE, 
DECWSS$TCPIP_OPEN, 
transport_read_queue, 
transport_read_ast : NOVALUE, 
transport_open_callback : NOVALUE, 
detach_and_poll : NOVALUE, 
reattach_ast : NOVALUE, 
DECWSSTCPIP_RUNDOWN : NOVALUE , 
DECWSTRANSPORT_INIT ; 





(continued on next page) 


Writing Your Own Transport 
8.3 Sample TCP/IP Transport Layer Implementation 


Example 8-2 (Cont.) TCP/IP Transport Layer Setup 





@ macro 


‘UCXS$DEVICE’ &, 
‘UCXSINET_HOST’ %, 


inet_dev_str 
inet_local_node 


swap_long( val ) = ( ( (val * 24) AND %X’FFO00000’) OR ( (val * 8 ) 
AND %X’FFO000’) OR ( (val * -8) AND %X’FFOO’) OR ( (val * -24 ) 
AND %$X’FF’) ) &%, 
swap _short( val ) = ( ( (val * 8) AND %X’FFOO’) OR ( (val * -8) AND %X’FF’) ) &%, 


xtcc_status( xtcc, status ) = 

IF NOT .xtcc [xtcc$v_err_sts_valid] 

THEN 
BEGIN 
xtcce [xtcc$l_err_status] = status ; 
xtcc [xtcc$v_err_sts_valid] =1; 
END %, 


load_desc( desc, string ) = BEGIN desc [0] = %CHARCOUNT( string ) ; 
desc [1] = UPLIT( string ) ; END % ; 


@ LITERAL 


© own 


REATTACH_ INTERVAL _SECS = 60, 
USER_WRITE_BY COPY = 1, 
ASYNC_EFN = 31, 

WRITE MAXIMUM LENGTH = 32768, 
INET _NODE_NAME LEN = 256 
BASE_TCP PORT = 5000 ; 


reattach timer _id : INITIAL( 0 ), 

reattach_timer_ delta : VECTOR[2] INITIAL( 0, 0 ), 
inet_dev_desc : VECTOR[2], 

tepip tft : $BBLOCK [xtft$c_length], 

tcepip tdb : REF $BBLOCK, 

local_node : $BBLOCK [INET _NODE_NAME LEN], 
lnn_desc : $BBLOCK [DSC$S_DSCDEF1] ; 


@ EXTERNAL ROUTINE 


DECWS$XPORT_FREE_INPUT, 
DECWS$$XPORT_WRITE, 
DECWSXPORT_CLOSE, 
DECWSXPORT_FREE_INPUT_BUFFER, 
DECW$XPORT_COPY_AND_ WRITE, 
DECWSXPORT_ALLOC_INIT_QUEUES, 
DECWS$XPORT DEALLOC_QUEUES, 
DECWS$XPORT_ALLOC_PMEM, 
DECWS$XPORT_DEALLOC_PMEM : NOVALUE, 
DECWSXPORT_VALIDATE_STRUCT, 
DECWSXPORT_VALIDATE_STRUCT_JSB : L_VALIDATE_ STRUCT, 
DECWSXPORT_ACCEPT FAILED, 
DECWSXPORT_ATTACHED, 
DECWS$XPORT_ATTACH_LOST, 
DECW$XPORT_REATTACH_FAILED, 
DECWS$XPORT_REFUSED_BY_SERVER ; 
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@ The included files are as follows: 


SYS$LIBRARY:STARLET includes the VAX/VMS System Service 
definitions. 


SYS$LIBRARY:UCX$INETDEF.R32 includes the definitions for 
the UCX product, the TCP/IP implementation upon which this 
example is layered. 


SRC$:XPORTEXAMPLEDEF.R32 includes the TCP/IP transport- 
specific structure definitions. 


SYS$LIBRARY:DECW$XPORTMAC.R32 includes the transport 
layer support macros. 


SYS$LIBRARY:DECW$XPORTMSG.R32 includes the transport 
layer message symbols. 


@ Define the program section (PSECT) names for the four PSECTs 
that BLISS implicitly uses. Code and static data should be position 
independent and shareable, while OWN and global data should be 
position independent and nonshareable. You may choose the PSECT 
names, but the PSECT attributes should obey these rules and be used 
in the link command. 


© Forward declarations for the procedures and routines that are defined 
in this module. 


@ Define the following macros to be used in this module: 


inet_dev_str is the logical name that identifies UCX’s controlling 
device. 


inet_local_node is the logical name that contains the name of the 
local host. 


swap_long converts between little-endian and big-endian 
unsigned longword integer formats. 


swap_short converts between little-endian and big-endian 
unsigned word integer formats. 


xtec_status stores a condition code in an XTCC’s error status field 
(XTCC$L_ERR_STATUS) exactly once. 


load_desc builds a 2-longword string descriptor suitable for 
system services and internal descriptors. 


© Define the following constants used in this module: 


REATTACH_INTERVAL_SECS controls the number of seconds 
between transport restart attempts. 


USER_WRITE_BY_COPY controls whether the DECW$$TCPIP_ 
WRITE_USER routine implements its function as a call to the 
common transport DECW$XPORT_COPY_AND_ WRITE routine. 


ASYNC_EFN is the number of the event flag to be used in 
asynchronous network I/O operations. Event flag 31 is used for 
such operations by convention. 
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WRITE_MAXIMUM_LENGTH has meaning only if USER_ 
WRITE_BY_COPY tests false. Then, the DECW$$TCPIP_ 
WRITE_USER routine implements a “true” write-from-user’s- 
buffer function and the value of this literal is the maximum size of 
any one $QIO. It should be a multiple of 4 and representable in 15 
bits. 


INET_NODE_NAME_LEN is the maximum length of any 
Internet node name. 


BASE_TCP_PORT is the TCP/IP port used by server number 0. 
The convention for TCP/IP is that server number 0 listens on port 
6000. Port 5000 is used in this example to prevent collision with a 
“real” TCP/IP transport. 


© Allocate the following data structures that are private to this 
transport: 


reattach_timer_id is the identifier of this timer. 


reattach_timer_delta is the time to wait between polling 
attempts. 


inet_dev_desc is a 2-longword descriptor of the name of UCX’s 
controlling device (macro inet_dev_str). It is initialized in the 
DECW$$TCPIP_ATTACH_TRANSPORT routine. 


tepip_tft is the XTFT structure for the TCP/IP transport. It is 
initialized in the DECW$TRANSPORT_INIT routine. 


tepip_tdb is the address of the XTDB allocated by the common 
transport on behalf of the TCP/IP transport. It is initialized in the 
DECW$$TCPIP_ATTACH_TRANSPORT routine. 


local_node is where the translation of the local node name 
logical name (UCX$DEVICE) is stored. It is initialized in the 
DECW$$TCPIP_ATTACH TRANSPORT routine. 


Inn_desc is a 2-longword descriptor for the logical name 
that represents the local node name. It is initialized in the 
DECW$$TCPIP_ATTACH_TRANSPORT routine. 


@ Declare all references to external procedures. These are all resident in 
the common transport shareable image. 


Sample XTFT$A_EXECUTE_WRITE Routine 


XTFT$A_EXECUTE_WRITE is invoked to write an XTCB to a transport 
connection. 


The procedure is expected to remove the head XTCB from the output work 
queue and, if the remove was successful, initiate I/O on the data in the 


XTCB. 


Note that the xtcb parameter in the call sequence is merely a placeholder 
retained for historical reasons; its value is never accessed or relied upon. 
Example 8-3 shows a sample implementation of the XTFT$A_EXECUTE_ 
WRITE routine. 
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Example 8-3 Sample XTFT$A_EXECUTE_WRITE Routine 





ROUTINE DECWSSTCPIP_EXECUTE_WRITE ( 
xtce: REF SBBLOCK, 
xtcb: REF S$SBBLOCK, 
mode 

) = 


BEGIN 

BUILTIN 
REMQHI ; 

LOCAL 
tcb : REF SBBLOCK, 
status ; 


Or nor xport_out_write_disable( xtcc ) 
THEN 
BEGIN 
@ WHILE ( status = REMQHT( .xtcc [xtcc$a_ow_queue], tcb ) ) 
EQL xport$k_queue_locked DO 
WHILE ..xtcc [xtcc$a_ow_queue] DO ; 
IF .status EQL xport$k_queue_no_ entry 


THEN 
xport_out_write_enable( xtcc ) 
ELSE 
© RETURN DECWSS$XPORT_WRITE( .xtcc, .tcb, .mode ) ; 
END ; 
SS$_NORMAL 
END ; 





@ If write operations are enabled, then disable them and execute the 
following block. Otherwise, leave them disabled and return. 


@ Attempt to remove an XTCB from the head of the output work 
queue. If there was no XTCB on the work queue, enable future write 
operations and return. 


© Ifthe queue was not empty, initiate a write operation for the XTCB 
by invoking the common transport routine (DECW$$XPORT_WRITE). 
This form of write operation expects a “real” XTCB in the argument 
list, not just a placeholder. 


8.3.3 Sample XTFT$A_WRITE Routine 


The XTFT$A_WRITE routine is invoked to write an XTCB to a transport 
connection. Unlike XTFT$A_EXECUTE_WRITE, the XTCB parameter 
in the argument list is significant and is the address of an XTCB, not an 
element of any queue, whose data is to be written to a connection. 


Writing Your Own Transport 
8.3 Sample TCP/IP Transport Layer Implementation 


Example 8—4 shows a sample implementation of the XTFT$A_WRITE 
routine. 


Example 8-4 Sample XTFT$A_WRITE Routine 





GLOBAL ROUTINE DECWSS$TCPIP_WRITE( itcc : REF $BBLOCK VOLATILE, tcb : REF 
SBBLOCK, mode ) = 


BEGIN 
BUILTIN 
TESTBITCS, 
TESTBITCC ; 
BIND 
xtpb = .itcce [ixtcc$a_tpb] : SBBLOCK, 
xtcc = .itcc [ixtcc$a_tcc] : $BBLOCK, 
xtcb = .tcb : SBBLOCK ; 
LOCAL 
status ; 


Or .xtcc [xtcc$v_dying] 
THEN 
BEGIN 
SINSQHI( xtcb, .itec [ixtcc$a_ow_queue] ) ; 
RETURN DECW$_CNXABORT ; 
END ; 
@ir .xtcb [xtcb$l_length] GTRU xport_xtcb_total( xtcb ) 
THEN 
RETURN SS$_IVBUFLEN ; 


Or .xtcb {[xtcb$l_length] EQLU 0 


THEN 

BEGIN 
IF .xtcb [xtcb$b_subtype] EQLU decw$c_dyn_xtcb_srp 
THEN 

status = SINSQHI( xtcb, .itcc [ixtcc$a_ofs_ queue] ) 
ELSE 

status = S$INSQHI( xtcb, .itcce [ixtcc$a ofl _queue] ) ; 

Or .status EQL xport$k_queue_corrupted 
THEN 
BEGIN 


xtcc [xtcc$v_dying] = 1 ; 
xtcc_status( xtcc, DECW$_BADQUEUE ) ; 
RETURN DECW$_CNXABORT ; 

END ; 


RETURN SS$_NORMAL ? 
END ; 





(continued on next page) 
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Example 8-4 (Cont.) Sample XTFT$A_WRITE Routine 


@ xtcb [xtcb$l_rflink] = xtcc ; 
IF NOT (status = $QIO( EFN =.itce [ixtcc$w_efn], 


FUNC = I0$_WRITEVBLK, 
CHAN = .itcce [ixtcc$w_chan], 
IOSB = xtch [xtcb$w_iosb], 


ASTADR = write ast, 

ASTPRM = xtcb, 

Pl = xtcb [xtcb$t_data], 

P2 = .xtcb [xtcb$l_ length] ) ) 


© THEN 

BEGIN 
SINSQHI( xtcb, .itcc [ixtcc$a_ow_queue] ) ; 
xtcc [xtcc$v_dying] = 1 ; 
xtcc_status( xtcc, .status ) ; 
END ; 

-Status 

END ; 


@ See if the connection is marked dying. If so, return the XTCB to the 
head of the output work queue and return with a status indicating 
that the connection has died. 


@ This is a consistency check on the information provided in the XTCB. 
If it is bad, return a fatal status. 


© If this XTCB is empty, return it to either the large or small output free 
queue, as appropriate for the XTCB type in the XTCB$B_SUBTYPE 
field, and return with a successful status. 


@ Ifthe queue was found to be corrupted, close the connection and return 
with a fatal status. 


@ The XTCB has a valid data length. Initiate a write $QIO on the 
data in the XTCB. P1 is the address of the first byte of user data 
in the XTCB; P2 is the length of the data in the buffer. The 
ASTADR argument specifies a WRITE_AST routine, as described 
in Section 8.3.4. ASTPRM is the address of the XTCB being operated 
on. 


© Ifthe $QIO service failed, return the XTCB to the head of the output 
work queue and mark the connection as dying. Use the XTCC_ 
STATUS macro to save the failure code in the XTCC if it has not 
yet been set. 
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8.3.4 Sample WRITE_AST Routine 


WRITE_AST is an AST completion routine for TCP/IP write operations. 
WRITE_AST returns the XTCB to the appropriate free queue. If the $QIO 
failed or the connection is dying, failure processing is performed and the 
transport prohibits further operations on this connection. 


Failure processing is dependent upon the type of transport being used. In 
the case of the TCP/IP implemented by UCX, a failed I/O attempt to the 
connection indicates that a connection has aborted. When an I/O operation 
completes and the status indicates failure, the code must perform all 
logical-link rundown operations including setting the dying bit and error 
status, completing any process waits for input or output, and sending 
notification to the process that the connection has died. 


Other transports such as DECnet provide a separate mechanism for 
receiving notice that a connection has aborted. For such a transport, these 
logical-link rundown operations need only be performed by the code that 
receives this notification. 


If the I/O completed successfully, the procedure attempts to remove 
another XTCB from the head of the output work queue and initiate a 
write operation on this XTCB. If the queue was empty, the procedure must 
enable write operations on the connection to cause the common transport 
to call the specific transport when an XTCB is next inserted on the output 
work queue. If the queue was not empty, the I/O operation is performed 
and the usual error processing is performed on the result. Example 8-5 
shows a sample implementation of the WRITE_AST routine. 


Example 8-5 Sample WRITE_AST Routine 





ROUTINE write_ast( xtcb : REF $BBLOCK ) : NOVALUE = 


BEGIN 
BIND ; 
tee = .xtcb [xtcb$l_rflink] : $BBLOCK, 

iosb = xtcb [xtcb$w_iosb] : VECTOR [4,WORD,UNSIGNED] ; 


BUILTIN 
TESTBITCS ; 


LOCAL 
itcc : REF S$BBLOCK, 
tcb : REF SBBLOCK, 
status, 
type ; 


0 
VALIDATE_XTCC( tcc, itcc ) ; 
IF .xtcb [xtcb$b_subtype] EQLU decwS$c_dyn_xtcb_srp 
THEN - 
BEGIN 
BIND 
xtpb = .itce [ixtcc$a_tpb] : $BBLOCK ; 


(continued on next page) 
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Example 8-5 (Cont.) Sample WRITE_AST Routine 





status = SINSQHI( .xtcb, .itcce [ixtcc$a_ofs_queue] ) ; 
xport_out_notify send( tcc, xtpb, decw$c_xport_buffer_srp ) ; 
END 
ELSE 
BEGIN 
BIND 
xtpb = .itcce [ixtcc$a_tpb] : S$BBLOCK ; 


status = S$INSQHI( .xtcb, .itcc [ixtccS$a_ofl_queue] ) ; 
xport_out_notify send( tcc, xtpb, decw$c_xport_buffer_lrp ) ; 
END ; 


IF .status EQL xport$k_queue_corrupted 
THEN 
BEGIN ( 
BIND 

xtpb = .itcc [ixtcc$a_tpb] : SBBLOCK ; 


IF TESTBITCS( tcc [xtcec$v_dying] ) 
THEN 
BEGIN 
xport_abort_send( tcpip _tdb, tcc ) ; 
IF .tcce [xtcc$v_lrp_on_output] 
THEN xport_out_notify send( tcc, xtpb, decw$c_xport_buffer_l1rp ) 
ELSE xport_out_notify _send( tcc, xtpb, decw$c_xport_buffer_srp ) ; 
xport_in_notify send( tcc, xtpb ) ; ( 
END ; 


xport_out_write_enable( tcc ) ; 
xport_write_unwait( tcc, xtpb ) ; 
xtcc_status( tcc, DECW$ BADQUEUE ) ; 
RETURN ; 

END ; 


Orr .tcc [xtcc$v_dying] OR NOT .iosb [0] 
THEN 
BEGIN 
BIND { 
xtpb = .itce [ixtcc$a_tpb] : $BBLOCK ; 


IF TESTBITCS( tec [xtcc$v_dying] ) 
THEN 
BEGIN 


xport_abort_send( tcpip_tdb, tcc ) ; 

IF .tce [xtcc$v_lrp_on_output] 

THEN xport_out_notify_send( tcc, xtpb, decw$c_xport_buffer_lrp ) 
ELSE xport_out_notify send( tcc, xtpb, decw$c_xport_buffer_srp ) ; 
xport_in_notify_send( tcc, xtpb ) ; 

END ; 


© xport_out_write enable ( tec ) ; 
xport_write_unwait( tcc, xtpb ) ; 
xtcc_status( tcc, .iosb [0] ) ; 
RETURN ; 
END ; 





(continued on next page) 
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Example 8-5 (Cont.) Sample WRITE_AST Routine 





@ status = SREMQHI( .itcce [ixtcc$a_ow_queue], tcb ) ; 


IF 


IF 


-Status EQL xport$k_queue_corrupted 
THEN 


BEGIN 
BIND 
xtpb = .itcc [ixtcc$a_tpb] : $BBLOCK ; 


IF TESTBITCS( tcc [xtcc$v_dying] ) 

THEN 
BEGIN 
xport_abort_send( tcpip _tdb, tcc ) ; 
IF .tcce [xtcc$v_lrp_on_output] 


THEN xport_out_notify send( tcc, xtpb, decw$c_xport_buffer_lrp ) 
ELSE xport_out_notify send( tcc, xtpb, decwS$c_xport_buffer_srp ) ; 


xport_in notify _send( tcc, xtpb ) ; 
END ; 


xport_out_write_enable( tcc ) ; 
xport_write _unwait( tcc, xtpb ) ; 
xtcc_status( tcc, DECWS_BADQUEUE ) ; 
RETURN ; 

END ; 


-Status EQL xport$k_queue_no entry 


THEN 


BEGIN 
BIND 

xtpb = .itcc [ixtcc$a_tpb] : $BBLOCK ; 
xport_out_write_enable( tcc ) ; 
xport_write unwait( tcc, xtpb ) ; 
RETURN ; 
END ; 


Occb [xteb$l_rflink] = tcc ; 
IF NOT ( status = Sqio( EFN = .itcc [ixtcc$w_efn], 


FUNC = I10$_WRITEVBLK, 

CHAN -itcc [ixtcc$w_chan], 
IOSB = tcb [xtcb$w_iosb], 
ASTADR = write_ast, 

ASTPRM = .tcb, 

Pl = tcb [xtcb$t_data], 

P2 = .tcbh [xtcb$l_length] ) 


THEN 


BEGIN 
BIND 
xtpb = .itcc [ixtcc$a_tpb] : $BBLOCK ; 





(continued on next page) 
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Example 8-5 (Cont.) Sample WRITE_AST Routine 


@ sInsoHT ( -tcb, .itcc [ixtcc$a_ow_queue] ) ; 

IF TESTBITCS( tcc [xtcc$v_dying] ) 

THEN 
BEGIN 
xport_abort_send( tcpip_tdb, tcc ) ; 
xport_in_notify_send( tcc, xtpb ) ; 
xtcc_status( tcc, .status ) ; 
END ; 

xport_write_unwait( tcc, xtpb ) ; 

END ; 

END ; 


@ First, assume that the write operation worked and put the buffer back 
on either the small or large OutputFreeQueue. The XPORT_OUT_ 
NOTIFY_SEND macro informs the process that a write operation has 
completed. This operation may consist of sending a user-mode AST to 
the process, or of code that completes the $SYNCH system service call 
performed by the XPORT_OUT_WAIT macro. 


If the output free queue was corrupted, perform failure processing to 
close this connection. ( 


@ In the case of TCP/IP under UCX, this procedure must detect and 
respond to any problem on the connection/socket. If the $QIO 
failed, and the connection is not yet marked as dying, then mark 
it. Additionally, invoke the XPORT_ABORT_SEND macro to declare a 
user-mode AST to the process indicating that the connection has died. 
Invoke the XPORT_OUT_NOTIFY_SEND and XPORT_IN_NOTIFY_ 
SEND macros to complete any $SYNCH service used to wait for this 
connection. 


© Allow write operations. The XPORT_WRITE_UNWAIT macro tests the 
XTCC$V_WAIT_ON_WRITE flag to see if it is set. If set, the common 
transport is waiting for the specific transport to empty the output 


work queue so that a write-user operation can be initiated. XPORT_ 
WRITE_UNWAIT clears the XTPB$W_ON_EEFN flag. 


Note: Most transports should implement the write-user function as 
a call to DECW$COPY_AND_WRITE and need not invoke the 
XPORT_WRITE_UNWAIT macro. 


Save the reason for the link abort and return. 


@ The I/O operation was successful, so attempt to get another XTCB 
from the output work queue. If it is empty, enable write operations on 
this connection and call XPORT_WRITE_UNWAIT. If the queue was 
corrupted, close the connection and perform abort processing. 


© There was an XTCB on the output work queue. Initiate a write $QIO ( 
on the data. 
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© Ifthe $QIO does not return successfully, insert the XTCB back on the 
output work queue. Test and set the dying flag and perform abort 
processing if it was clear. 


Sample XTFT$A_WRITE_USER Routine 


The XTFT$A_WRITE_USER routine attempts to write a buffer in the 
user’s address space to a TCP/IP connection. The purpose of this interface 
is to avoid a data copy into XTCBs when the caller has a large, contiguous 
block of data to be written to a connection, such as when sending image 
data between client and server. 


There are two methods for implementing the XTFT$A_WRITE_USER 
routine. The first is to wait for the output work queue to become empty 


and then perform the I/O operation on the user’s buffer, typically by means 
of a $QIO. 


The other method is to invoke the common transport’s DECW$XPORT_ 
COPY_AND_WRITE routine with the user’s buffer as an argument. Due 
to the way this feature is being used in the DECwindows software, it is 
strongly recommended that transports use the DECW$XPORT_COPY_ 
AND_WRITE routine. 


Example 8-6 shows a sample implementation of the XTFT$A_WRITE_ 
USER routine. 


Example 8-6 Sample XTFT$A_WRITE_USER Routine 


GLOBAL ROUTINE DECWSSTCPIP_WRITE_USER( itcc : REF $BBLOCK VOLATILE, buffer : 
REF $BBLOCK, mode ) = 


BEGIN 

BUILTIN 
TESTBITCS, 
TESTBITCC, 
INSQTI, 
INSQHI, 
REMOQHI ; 


BIND 
xtcc 
xtpb 


LOCAL 
status, 
data_adr, 
data_len, 
size, 
lcl_iosb : VECTOR[4,WORD, UNSIGNED] ; 


-itce [ixtcc$a_tcc] : $BBLOCK, 
.itcc [ixtcc$a_tpb] : $BBLOCK ; 


tt fl 


Or .xtcc [xtcc$v_dying] 
THEN 
BEGIN 
RETURN DECWS_CNXABORT ; 
END ; 


(continued on next page) 
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Example 8-6 (Cont.) Sample XTFT$A_WRITE_USER Routine 





Or (data_adr 
OR 
(data_len 
THEN 
RETURN SS$_NORMAL ; 


-buffer [dsc$a_pointer]) EQLA 0 


-buffer [dsc$w_length]) EQLU 0 


© %1F USER_WRITE_BY COPY 
$THEN 


@ status = DECWS$XPORT_COPY AND WRITE( xtcc, 0, .data_adr, 
-data_len, size ) ; 


SELSE 


e 
(xtcce [xtcc$w_ow_iosb])< 0,32, 0> = 0; 
(xtcc [xtcc$w_ow_iosb])<32,32, 0> = 0 ; 
TESTBITCS( (xtcc [xtcc$l_flags])<SBITPOSITION( xtcc$v_wait_on_write ), 1>) ; 
© wHILe (xport_out_write disable( xtcc )) DO 
BEGIN 
xport_write wait( xtcc, xtpb ) ; 
END ; 


@ xport_out_write enable ( xtcc ) ; 
TESTBITCC( (xtcc [xtcc$l_flags])<SBITPOSITION( xtcc$v_wait_on_write ), 1>) ; 


@Ir .xtcc [xtccSv_dying] 
THEN 

BEGIN 
RETURN DECWS$_CNXABORT ; 
END ; 

@ do 
BEGIN 
size = MINU( WRITE MAXIMUM LENGTH, -data_len ). 3 


@ ir (status = $QIOW(EFN = .itcc [ixtcc$w_efn], 


FUNC = IO$_WRITEVBLK, 
CHAN = .itcce [ixtcc$w_chan], 
IOSB = 1lcl_iosb, 
Pl = .data_adr, 
P2 = .size ) ) 
THEN 
status = .lcl_iosb [0] ; 
IF NOT .status 
THEN 
RETURN .status ; 
data_len = .data_len - .size ; 
data_adr = .data_adr + .size ; 
END 
WHILE .data_len NEQU 0 ; 
SFI 
® . status 


END ; 





@ Ifthe dying field is set, return an abort status. 
@ Ifthe address or length of the data equals zero, we are done. 
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In the code developed by Digital, the BLISS literal USER_WRITE_ 
BY_COPY is always set to the value 1 and the code that invokes 
the DECW$XPORT_COPY_AND_WRITE procedure is compiled. For 
completeness, the uncompiled code is also described. 


Invoke the common transport DECW$XPORT_COPY_AND_WRITE 
routine to copy the data in the user’s buffer into XTCBs and make 
them available for transmission to the connection. 


Clear the waiting-for-output IOSB field of the XTCC and set the 
XTCC$V_WAIT_ON_WRITE bit to indicate that it is waiting for the 
output work queue to become empty. This operation is similar to the 
operation performed by the XPORT_IN_NOTIFY_SET and XPORT_ 
OUT_NOTIFY_SET macros. 


Begin waiting for the output work queue to empty. The wait is 
required to ensure that the data sent to the connection is not 
reordered. When the output work queue is emptied, writing is 
enabled on the connection, hence the WHILE loop. Invoke the XPORT_ 
WRITE_WAIT macro inside the loop to perform the $SYNCH service. 


The wait has been satisfied, so continue processing the write-user 
request. The XPORT_OUT_WRITE_DISABLE macro tests and sets 
the disable flag, so enable write operations (this is a branch-on-bit- 
clear-and-clear-interlocked (BBCCI) instruction). Clear the XTCC$V_ 
WAIT_ON_WRITE bit. 


Check if the connection is dying. Wakeup may be due to connection 
abort. 


Begin a loop that writes the user’s data. For very large user data 
blocks, it may be necessary to break the data into smaller pieces 
for transmission. The optimal size of these pieces may be different 
for each type of transport. In the example, this size is given by the 
literal WRITE_MAXIMUM_LENGTH, which is a value that can be 
represented by a 15-bit integer. 


Write the data to the connection using the $QIOW system service. The 
wait form of the service is required because the user’s buffer is not 
safely copied until the I/O request completes. 


Return the status. 


Sample XTFT$A_EXECUTE_FREE Routine 


The XTFT$A_EXECUTE_FREE routine logically returns an XTCB to a 
local logical link. The common transport invokes XTFT$A_EXECUTE_ 
FREE after it returns an input XTCB to a previously empty free queue. 
XTFT$A_EXECUTE_FREE checks to see if input-free operations are 
enabled for this connection, and if so, attempts to start a read operation 
into an XTCB after removing it from the head of the queue. 


The tcb argument is a placeholder; it is never referred to by the routine 
and its contents are unpredictable. 
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Example 8-7 shows a sample implementation of the XTFT$A_EXECUTE_ 
FREE routine. 


Example 8-7 Sample XTFT$A_EXECUTE_FREE Routine 


ROUTINE DECWSS$TCPIP_EXECUTE_FREE ( 
tec: REF SBBLOCK, 
tcb: REF SBBLOCK, 
type, 
free queue 
) = 
BEGIN 
BUILTIN 
REMOQHI ; 
LOCAL 
newtcb : REF SBBLOCK, 
status ; 


Or NOT xport_in_free_disable( tcc, .type ) 
THEN 
BEGIN 
@ wHILE (status = REMOQHI( .free_queue, newtcb )) EQL xport$k_queue_locked DO 
WHILE ..free queue DO ; 


Or .status EQL xport$k_queue_no_ entry 
THEN 
BEGIN 
xport_in_free_enable( tcc, .type ) ; 
status = SS$ NORMAL ; 
END 
@ ELSE 
RETURN DECWSS$XPORT_FREE_INPUT( .tcc, .newtcb ) ; 
END ; 


SS$_NORMAL 
END ; 


@ If free-input operations are disabled, leave them disabled and return a 
successful status. No additional work is necessary. 


@ Free-input operations that were enabled are now disabled. Attempt 
to remove an XTCB from the appropriate free queue. If the queue is 
locked, test the interlock bit of the free queue until it is no longer set, 
then go back and do the remove operation again. 


© Ifthe queue was empty this was a false start. Enable free-input 
operations and return a successful status. 


© Otherwise, invoke XTFT$A_FREE_INPUT_BUFFER by means of the 
common transport DECW$$XPORT_FREE_INPUT routine to start a 
read operation on the XTCB removed from the queue. 
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8.3.7. Sample XTFT$A_FREE_INPUT BUFFER Routine 


The XTFT$A_FREE_INPUT_BUFFER does an asynchronous read, by 
means of a $QIO read, for a connection into the provided buffer. The 
common transport invokes XTFT$A_FREE_INPUT_BUFFER when an 
input XTCB has been returned by the caller to a transport and the specific 
transport needs to receive control in order to initiate a read operation. 


Unlike the XTFT$A_EXECUTE_FREE routine, the xtcb argument is a 
“real” XTCB. It is assumed that any enable/disable checks, performed with 
the XPORT_IN_FREE_DISABLE macro, have already been performed. 


Example 8-8 shows a sample implementation of the XTFT$A_FREE_ 
INPUT_BUFFER routine. 


Example 8-8 Sample XTFT$A_FREE_INPUT_BUFFER Routine 


GLOBAL ROUTINE DECWSSTCPIP_FREE_INPUT_BUFFER( itcc : REF $BBLOCK VOLATILE, tcb 
: REF SBBLOCK ) = 


BEGIN 

BIND 
xtcb 
xtecc 
xtpb 


-tcb : SBBLOCK, 
-itce [ixtcc$a_tcc] : $BBLOCK, 
-itce [ixtcc$a_tpb] : $BBLOCK ; 


LOCAL 
status, 
size, 
free queue ; 


@Ir .xtcb [xtcb$b_subtype] EQLU decw$c_dyn_xtcb_srp 


THEN 
free queue = .itcce [ixtcc$a_ifs queue] 
ELSE 
free_queue = .itcce [ixtcc$a_ifl_queue] ; 
@ xtcb [xtcb$l_rflink] = xtcc ; 


IF NOT (status = $QIO( EFN = .itcc [ixtcc$w_efn], 
CHAN = .itcce [ixtcc$w_chan], 
FUNC = IO$_READVBLK, 

IOSB = xtcb [xtcb$w_iosb], 
ASTADR = free_input_ast, 
ASTPRM = xtcb, 


Pl = xtcb [xtcb$t_data], 
P2 = xport_xtcb_total( xtcb ) ) ) 
© THEN 
BEGIN 
SINSQHI( xtcb, .free_queue ) ; 
xtcc [xtcc$v_dying] = 1 ; 
xtcc_status( xtcc, .status ) ; 
END ; 
-status 


END ; 
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@ Determine which free queue this XTCB came from, based on the 
XTCB$B_SUBTYPE field of the XTCB. 


@ Store the address of the connection structure in the XTCB and then 
initiate an asynchronous read $QIO into the XTCB. The FREE_ 
INPUT_AST read-completion AST routine is called with the address of 
the XTCB when the I/O operation completes. The FREE_INPUT_AST 
routine is described in Section 8.3.8. 


© Ifthe $QIO service failed, perform failure recovery. Return the XTCB 
to the correct free queue, mark the connection as dying, and store the 
failure status code in the XTCC with the XTCC_STATUS macro. 


In either case, return the result of the $QIO service as the return 
value. 


8.3.8 Sample FREE_INPUT_AST Routine 


The FREE_INPUT_AST routine is the $QIO read-completion AST routine. 
It performs a number of steps based on the type of transport being used. 
Example 8-9 shows a sample implementation of the FREE_INPUT_AST 
routine. 


Example 8-9 Sample FREE_INPUT_AST Routine 


ROUTINE free _input_ast( xtcb : REF SBBLOCK ) : NOVALUE = 


BEGIN 
BUILTIN 
TESTBITCS ; 
BIND 
tee = .xtcb [xtcb$l_rflink] : $BBLOCK ; 
LOCAL | 


itcc : REF SBBLOCK, 
tpb : REF SBBLOCK, 

status, 

tcb : REF SBBLOCK, 

type, 

free_queue ; 


VALIDATE_XTCC( tcc, itcc ) ; 
tpb = .itce [ixtcc$a_tpb] ; 


@ status = $INSQTI( .xtcb, .itcce [ixtcc$a_iw_queue] ) ; 
@ IF .status EQL xport$k_queue_corrupted 
THEN 
BEGIN 
BIND 


xtpb = .itcce [ixtcc$a_tpb] : SBBLOCK; 


(continued on next page) | 
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IF TESTBITCS( tcc [xtcc$v_dying] ) 
THEN 
BEGIN 
xport_abort_send( tcpip_tdb, tcc ) ; 
IF .tcce [xtcc$v_lrp_on_output] 
THEN xport_out_notify_ send( tcc, xtpb, decw$c_xport_buffer_lrp ) 
ELSE xport_out_notify send( tcc, xtpb, decw$c_xport_buffer_srp ) ; 
xport_in notify send( tcc, xtpb ) ; 
END ; 


© xport_out_write enable ( tec ) 
xport_write_unwait( tcc, xtpb ) ; 
xtcc_status( tcc, DECWS$_BADQUEUE ) ; 
RETURN ; 
END ; 


BEGIN 
BIND 
xtpb = .itcc [ixtcc$a_tpb] : $BBLOCK, 
iosb = xtcb [xtcb$w_iosb] : VECTOR [4,WORD,UNSIGNED] ; 


@ir .tce {xtcc$v_dying] OR NOT .iosb [0] 
THEN 

BEGIN 

IF TESTBITCS( tcc [xtcec$v_dying] ) 

THEN 
BEGIN 
xport_abort_send( tcpip_tdb, tcc ) ; 
IF .tcc [xtcc$v_lrp_on_output] 
THEN xport_out_notify_send( tcc, xtpb, decw$c_xport_buffer_lrp ) 
ELSE xport_out_notify _send( tcc, xtpb, decw$c_xport_buffer_srp ) ; 
xport_in notify send( tcc, xtpb ) ; 
END ; 


xport_out_write_enable( tcc ) ; 
xport_ write unwait( tcc, xtpb ) ; 
xtcc_status( tcc, .iosb [0] ) ; 
RETURN ; 

END ; 





(continued on next page) 


8-21 


Writing Your Own Transport 
8.3 Sample TCP/IP Transport Layer Implementation 


Example 8-9 (Cont.) Sample FREE_INPUT_AST Routine 





© xtcb [xtcb$l_length] = .iosb [1] ; 
xtcbh [xtcb$a_pointer] = xtcb [xtcb$t_data] + .iosb [1] ; 
@ IF .iosb [1] LSSU .tpb [xtpbSw_srp_size] 


THEN 
BEGIN 
IF ( xport_in_state_srp( tcc ) ) 
THEN 
BEGIN 
xport_in free disable( tcc, decw$c_xport_buffer_lrp ) ; 
END ; 
type = decw$c_xport_buffer_srp ; 
free_queue = .itcc [ixtcc$a_ifs_queue] ; 
END 
ELSE 
BEGIN 
IF ( xport_in_state_lrp( tcc ) ) 
THEN 
BEGIN 
xport_in_ free disable( tcc, decw$c_xport_buffer_srp ) ; 
END ; 
type = decw$c_xport_buffer_lrp ; 
free_queue = .itcc [ixtcc$a_ifl_ queue] ; 
END ; 


@ status = $REMQHI( .free queue, tcb) ; 


IF .status EQL xport$k_queue_corrupted 
THEN 
BEGIN 
BIND 
xtpb = .itcc [ixtcc$a_tpb] : $BBLOCK ; 


IF TESTBITCS( tcc [xtcc$v_dying] ) 
THEN 
BEGIN 
xport_abort_send( tcpip_tdb, tcc ) ; 
IF .tcc [xtcc$v_lrp_on_output] 
THEN xport_out_notify send( tcc, xtpb, decw$c_xport_buffer_lrp ) 
ELSE xport_out_notify_send( tcc, xtpb, decw$c_xport_buffer_srp ) ; 
xport_in_ notify send( tcc, xtpb ) ; 
END ; 


xport_out_write _enable( tcc ) ; 
xport_write unwait( tcc, xtpb ) ; 
xtcc_status( tcc, DECW$_BADQUEUE ) ; 
RETURN ; . 


END ; 





(continued on next page) 
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IF .status NEQ xport$k_queue_no entry 
THEN 
BEGIN 
@tcb [xtcb$l_rflink] = tcc ; 
@ iF Nor status = $QI0( EFN = .itcc [ixtcc$w_efn], 


FUNC = IOS_READVBLK, 

= tcb [xtcb$w_iosb], 
ASTADR = free_input_ast, 
ASTPRM = .tcb, 
Pl = tcb [xtcb$t_data], 


P2 xport_xtcb_total( tcb ) ) 
® cHEN 
SINSQHI( .tcb, .free_queue ) ; 
END 
@ ELSE 
BEGIN 


IF .type EQLU decw$c_xport_buffer_srp 
THEN xport_in free enable( tcc, decw$c_xport_buffer_srp ) 
ELSE xport_in free _enable( tcc, decw$c_xport_buffer_lrp ) ; 
status = SS$ NORMAL ; 
END ; 

END ; 


@ ir nor .status 
THEN 
BEGIN 
BIND 
xtpb = .itcce [ixtcc$a_tpb] : $BBLOCK ; 


IF TESTBITCS( tcc [xtcc$v_dying] ) 
THEN 
BEGIN 
xport_abort_send( tcpip_tdb, tcc ) ; 
xport_in_ notify send( tcc, xtpb ) ; 
xtcce_status( tcc, .status ) ; 
END ; 
END ; 
xport_in_notify send( tcc, tpb ) ; 
END ; 





@ Insert the XTCB returned by the read operation on the tail of the 
input work queue. 


@ Ifthe queue was corrupted, this connection must be run down. Abort 
notification must be performed if this is the first attempt at rundown. 
This consists of conditionally declaring a user-mode AST for the link 
abort (by means of XPORT_ABORT_SEND), sending notification that a 
write operation has completed (to complete any output wait condition), 
and sending notification that a read operation has completed (to 
complete any input wait condition). 
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© Failure processing continues by enabling write operations, clearing 
any wait-for-empty-output-work-queue condition, saving the reason for 
the connection abort, and returning. 


@ Check the result of the read $QIO. If it failed, perform failure 
processing as done in the case of the corrupted queue. 


@ The read operation completed successfully, so initialize the XTCB$L_ 
LENGTH and XTCB$A_POINTER fields of the completed XTCB. 


© Determine whether the large or small XTCBs should be used in 

subsequent I/O operations. If the read operation that just completed 
filled a small XTCB, then shift up to the large XTCBs. Otherwise, if 
large XTCBs were being used and the last read operation would have 
fit in a small XTCB, then shift down to the small XTCBs. Otherwise, 
no change. At the end of this decision making, type contains the type 
of XTCB to be used and free_queue is the address of the free queue 
header from which these XTCBs are removed. 


@ Attempt to remove an XTCB from the free queue. If the queue was 
corrupted, perform failure processing. 


@ An XTCB was successfully removed from the queue. Save the 
connection structure address in the XTCB for use on reentry to this 
procedure. 


© Initiate an asynchronous read $QIO on this XTCB, specifying this 
routine as the read-completion AST routine. 


The I/O request failed, so return the XTCB to the free queue. 


There were no XTCBs on the free queue, so no more work can be done 
here. Enable free-input operations on the particular free queue being 
used and set status to normal completion. 


® The $QIO system service failed. Mark the connection as dying and, if 
this is the first time that it has been marked, perform connection-abort 
processing. Send input notification to complete any wait operation on 
the process. 


8.3.9 Sample XTFT$A_CLOSE Routine 


The XTFT$A_CLOSE routine initiates a series of operations that 
disconnect a connection and release the data structures associated with 
the link. Example 8-10 shows a sample implementation of the XTFT$A_ 
CLOSE routine. 
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Example 8-10 Sample XTFT$A_CLOSE Routine 





GLOBAL ROUTINE DECWSS$TCPIP_CLOSE( itcc : REF $BBLOCK VOLATILE) = 


BEGIN 

LOCAL 
tcc : REF SBBLOCK INITIAL( .itcce [ixtcc$a_tcc] ), 
Status ; 


Oitcc [xtcc$v_dying] = 1 ; 


@ scancEL ( CHAN = .itcc [ixtcc$w_chan] ) ; 
SDASSGN ( CHAN = .itcc [ixtcc$w_chan] ) ; 
itee [ixtcc$Sw_chan] = 0 ; 


@ status = $DCLAST( ASTADR 
ASTPRM 


close_and_deallocate_ast, 
eitee ) 7 


- Status 
END ; 


@ Mark the connection as dying, both to prevent the caller from 
requesting operations on this connection and to prevent the various 
completion AST routines from attempting to perform additional work. 


@ Cancel I/O and deassign the channel to the connection. This action 
completes all outstanding I/O operations to the connection and 
queues all completion ASTs. Further references to the channel are 
not permitted. 


© Declare an AST to the CLOSE_LAND_DEALLOCATE_AST routine that 
is executed after the completion ASTs. This routine performs the final 
cleanup operations such as structure invalidation and deallocation. 


8.3.10 Sample CLOSE_AND_DEALLOCATE_AST Routine 


The CLOSE_AND_DEALLOCATE_AST routine completes the connection 
close initiated by XTFT$A_CLOSE. Once this procedure executes, it is 
assumed that neither the transport caller nor any part of the transport 
will refer to this connection again. It is also assumed that all XTCBs have 
been returned to the communication queue structure (XTCQ). 


Example 8-11 shows a sample implementation of the CLOSE_AND_ 
DEALLOCATE_AST routine. 
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Example 8-11 Sample CLOSE_AND_DEALLOCATE_AST Routine 





ROUTINE close_and_deallocate_ast( itcc : REF $BBLOCK ) : NOVALUE = 


BEGIN 
BUILTIN 
REMQUE ; 


LOCAL 
tdb : REF SBBLOCK INITIAL( .itce [ixtcc$a_tdb] ), 
tpb : REF $BBLOCK INITIAL( .itcc [ixtcc$a_tpb] ), 
status ; 


@ REMQUE( .itcc, itce ) ; 
tdb [xtdb$l_ref count] = .tdb [xtdb$l_ref_count] - 1 ; 
@ DECWSXPORT_DEALLOC_QUEUES( .itcc ) ; 


© itcc {ixtccS$a_xport_table] = 0; 


© DECWSXPORT DEALLOC_PMEM( .itcc ) ; 
DECWS$XPORT_DEALLOC PMEM( .tpb ) ; 
END ; 


Remove the IXTCC from the IXTCC queue in the XTDB and decrement , 
the reference count in the XTDB. 


Deallocate the storage previously allocated for the connection queues. 


Zero the IXTCC$A_XPORT_TABLE field in the IXTCC to catch any 
subsequent references to the connection. 


Deallocate the IXTCC and XTPB connection structures. At this point, 
the connection is completely run down. 


Sample XTFT$A_OPEN Routine 


The XTFT$A_OPEN routine is invoked by a client to establish a 
connection to an X server. 


Example 8-12 shows a sample implementation of the XTFT$A_OPEN 
routine. 
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Example 8-12 Sample DECW$$TCPIP_OPEN Routine 





GLOBAL ROUTINE DECWSSTCPIP_OPEN( workstation : REF $BBLOCK, server, itcc : REF 
SBBLOCK ) = 


BEGIN 

BUILTIN 
REMQUE, 
INSQUE ; 


BIND 
tpb = .itcce [ixtcc$a_tpb] : $BBLOCK ; 


LOCAL 
socktype : INITIAL( (UCX$C_STREAM * 16) + UCXSC_TCP ), 
sockaddrin : $BBLOCK [SIN$S_SOCKADDRIN] PRESET ( 
{[SINSW_FAMILY] = INETSC_AF INET, 
[SINSW_PORT] = 0, 
[SINSL_ADDR] = swap_long( INETSC_INADDR_ANY ) ), 
sin_desc : VECTOR [2] INITIAL( SALLOCATION( sockaddrin ), sockaddrin ), 
server _addr : VECTOR [16,BYTE,UNSIGNED], 
server _desc : VECTOR [2] INITIAL( tALLOCATION( server_addr ) - 1, server_addr ), 
server_len : INITIAL( 0 ), 
stradr : REF VECTOR [,BYTE, UNSIGNED], 
sinadr : REF VECTOR [,BYTE, UNSIGNED], 
strlen, 
iosb : VECTOR [4,WORD, UNSIGNED], 
func_code : INITIAL( INETACP_FUNC$C_GETHOSTBYNAME ), 
func_code_ desc : VECTOR [2] INITIAL( tALLOCATION( func_code ), func_code ), 
status, 
success : INITIAL ( 0 ), 
tcb, 
tcc : REF $BBLOCK, 
free queue ; 


LABEL 
connect ; 


@ connect: 
BEGIN 

@ status = DECW$XPORT ALLOC INIT QUEUES( .itcc, 
-tcpip tft[xtft$l_xtcc_length], 
-tpb [xtpb$w_srp_size], 
-tpb [xtpb$w_lrp_ size], 
-tpb [xtpb$w_i_srp_count], 
-tpb [xtpb$w_i_lrp_ count], 
-tpb [xtpb$w_o_srp_count], 
-tpb [xtpb$w_o_lrp_ count], 
0, 
0); 


IF NOT .status 
THEN 
RETURN .status ; 
tee = .itcc[ixtccS8a_tec] ; 


© INSQUE( .itcc, tcepip_tdb [xtdbS$a_itcc_flink] ) ; 
tcpip_tdb [xtdb$l_ref_count] = .tcpip tdb [xtdb$l_ref_count] + 1 ; 





(continued on next page) 
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QO ir Nor (status = $assign( DEVNAM = inet_dev_desc, 
CHAN = itcc [ixtcc$w_chan], 
ACMODE = psl$c_user ) ) 
THEN 
LEAVE connect ; 


@ sockaddrin [SINSW_PORT] = 0; 
IF (status = $qiow( EFN = .tcpip_tdb [xtdb$w_efn], 
CHAN = .itcc [ixtcc$w_chan], 


FUNC = I0$_SETMODE, 

IOSB = iosb, 

Pl = socktype, 

P2 = ( %X’01000000’ OR INETSM_LINGER ), 
P3 = sin_desc ) ) 


THEN 

status = .iosb [0] ; 
IF NOT .status 
THEN 


LEAVE connect ; 


@ir -workstation [DSCSW_LENGTH] EQL 1 
AND .(.workstation [DSCSA_POINTER])<0,8,0> EQL %C’0’ 
THEN 
workstation = lnn_desc ; 


@ir (status = $qiow( EFN = .tcpip_tdb [xtdb$w_efn], 


CHAN = .itce [ixtcc$w_chan], 
FUNC = IO$_ACPCONTROL, 
IOSB = iosb, 


Pl = func_code_desc, 

P2 = workstation [0,0,0,0], 
P3 = server len, 

P4 = server_desc ) ) 


© THEN 
status = .iosb [0] ; 
IF NOT .status 
THEN 
IF .status NEQU SS$_ENDOFFILE 
THEN 
LEAVE connect ; 
© ELSE 
BEGIN 
IF .workstation [DSCSW_LENGTH] GEQU *ALLOCATION( server_addr ) 
THEN 
BEGIN 


status = DECWS_INVSRVNAM ; 
LEAVE connect ; 
END ; 
CHSMOVE( .workstation [DSC$W_LENGTH], .workstation [DSCSA_POINTER], 
server_addr ) ; 
server_len = .workstation [DSCSW_LENGTH] ; 
END ; 





(continued on next page) 
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® server_addr [.server_len] = %C’.’ 
server desc [0] = .server_len +1 ; 
sinadr = sockaddrin [SINS$L_ADDR] ; 
sockaddrin [SINSW_PORT] = swap_short( ( BASE_TCP_PORT + .server ) ) ; 
INCR i FROM 0 TO 3 


® do 
BEGIN 
sinadr [.i] = 0; 
stradr = .server desc [1] ; 
IF CHSFAIL( strlen = CH$FIND_CH( .server_desc [0], .server_desc [1], %C’.’ ) ) 
THEN 
BEGIN 


status = SS$_BADPARAM ; 
LEAVE connect ; 


END ; 
strlen = .strilen - .stradr ; 
INCR j FROM 0 TO ( .strlen - 1 ) 
DO 
BEGIN 
IF .stradr [.j] LSSU %C’0’ OR .stradr [.j] GTRU %C’9’ 
THEN 
BEGIN 
status = DECW$_INVSRVNAM ; 
LEAVE connect ; 
END ; 
sinadr [.i] = .sinadr [.i] * 10 + ( .stradr [.j] - %c’0’ ) ; 
END ; | 
server _desc [1] = .server_desc [1] + .strlen +1 ; 
server_desc [0] = ( .server_desc [0] - .strlen ) -1; 
IF ( .server_desc [0] LSS 0 ) 
THEN 
BEGIN 
status = SS$_BADPARAM ; 
LEAVE connect ; 
END ; 
END ; 


@ iF (status = Sqiow( EFN = .tcpip tdb [xtdb$w_efn], 
CHAN = .itce [{ixtcc$w_chan], 
FUNC = IO$_ACCESS, 
IOSB = iosb, 
P3 = sin_desc ) ) 


THEN 

status = .iosb [0] ; 
IF NOT .status 
THEN 


LEAVE connect ; 


icc [xtcc$l flags] 
tec [xtcc$v_mode] 
itece [ixtcc$a_tdb] 
itec [ixtcc$w_efn] 
itcce [ixtcc$a_xport_table] 


xtcc$m_active ; 
DECWSK_XPORT_REMOTE CLIENT ; 
-tcpip tdb ; 

-tcpip tdb [xtdb$w_efn] ; 

-tcpip tdb [xtdbSa_xport_table] ; 


iu 


® xport_in_state_srp( tcc ) ; 
xport_out_state_srp( tcc ) ; 
xport_in free disable( tcc, decw$c_xport_buffer_lrp ) ; 





(continued on next page) 
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® status = $REMQTI( .itcc [ixtcc$a_ifs_ queue], tcb ) ; 
IF (.status EQL xport$k_queue_corrupted) OR 


(.status EQL xport$k_queue_no_ entry) 


THEN 


BEGIN 

status = DECW$_BADQUEUE 7 
LEAVE connect ; 

END ; 


® xport_in free disable ( tcc, decw$c_xport_buffer_srp ) ; 
status = DECWSSTCPIP_FREE_INPUT_BUFFER( .itcc, .tcb ) ; 
RETURN .status ; 
END; 


@ ir .itce [ixtcc$w_chan] NEQU 0 
THEN 


SDASSGN( CHAN = .itcc [ixtcc$w_chan] ) ; 


REMQUE( .itcc, itcc ) ; 


tcpip_tdb [xtdb$l_ref_count] = .tcpip_tdb [xtdb$l_ref_count] - 1; 
RETURN .status ; 


END ; 
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@ Start a named block of code that attempts to allocate and initialize the | 
resources needed to maintain a connection. If any part of this setup 
fails, the code block exits and failure processing recovers any allocated 
resources. 


@ Call the transport-common DECW$XPORT_ALLOC_INIT_QUEUES 
routine to allocate and initialize the communication queues. 
DECW$XPORT_ALLOC_INIT_QUEUES allocates a block of storage 
for an XTCC, XTCQ, and all of the XTCBs for a connection. 
DECW$XPORT_ALLOC_INIT_QUEUES must allocate at least an 
XTCC; the other structures are optional. DECW$XPORT_ALLOC._. 
INIT_QUEUES places all of the XTCBs on the appropriate free queues. 


@ Insert the IXTCC on the XTDB’s queue of active connections so that 
the structure can be found if the rundown routine is invoked before 
the connection is fully started. Increment the XTDB$L_REF_COUNT 
field that tracks the number of connections using this transport. 


@ Assign a channel and create a socket to the Internet networking 
service. 


@ Initialize the sockaddrin structure to request an Internet-protocol 
socket on any available port. Perform a SETMODE $QIO system 
service to establish the desired characteristics on the socket. 


The Pl argument specifies a stream-mode, TCP/IP socket. 
The P2 argument enables the “linger” option on the TCP/IP socket. 


The P38 argument provides port, address, and address-family 
information for the socket. 


Writing Your Own Transport 
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If the transport caller requested a connection with a node-identifying 
string of “0”, use the Internet name of the host as the node string. 


Attempt to perform a name-to-address conversion with an IO$_ 
ACPCONTROL $QIO system service that queries the UCX host 
database. The IO$_ACPCONTROL arguments are as follows: 


¢ P1 specifies the function to be performed by the ACPCONTROL 
$QIO, which in this case requests a get-host-by-name conversion. 


¢ 2 is the address of a descriptor of the host name to search for in 
the host database. 


¢ P39 is the address of a word to receive the length of the returned 
address string. 


¢ P4 is the address of the descriptor of the storage to receive the 
address found by the search. 


© Ifthe $QIO failed and the reason was other than SS$_ENDOFFILE, 


cease processing. 


If the $QIO failed and the reason was SS$_ENDOFFILE, then the 
conversion request could not find the host name in the UCX host 
database. In this case, assume that the caller supplied the name of the 
node in Internet Standard Format (for example, 130.180.40.44). 


This is also the format of the result string returned by the 
GETHOSTBYNAME ACPCONTROL function, so continue as if the 
$QIO was successful and use the caller’s node argument as the result 
of the ACPCONTROL $QIO system service. 


Determine which TCP port to attach to on the server side and place 
this port number, in Network Standard Format, in the sockaddrin 
structure. The port number is the result of adding the server number 
to 5000. (5000 is used in this example to prevent collision with a “rea 
TCP/IP transport. In a “real” transport, this number would be 6000.) 


Attempt to convert the ASCII Internet Standard Format address into 
the binary, 32-bit Network Standard Format address. This entails 
converting numeric fields separated by periods into 1-byte values and 
then packing these bytes into a longword with the first-encountered 
field converted and inserted into the rightmost byte of the longword. 
For example, the address 130.180.40.44 would be converted to the 
longword value 2C28B482161.. 


If there are too few fields or any nonnumeric characters seen (other 
than the field separator), then fail and indicate a bad parameter or 
invalid server name. 


” 


If successful, the Network Standard Format address is built in the 
sockaddrin structure. 


Address conversion was successful, so attempt to attach to the 
server. This is done by invoking the $QIOW system service with 

an IO$_ACCESS function code. The P8 argument is the address of a 
descriptor of the sockaddrin structure that contains the address and 
port number of the server. 
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® Mark the connection as active by setting the flags longword of the 
XTCC to the constant XTCC$M_ACTIVE and the connection mode 
as a remote client. These two operations should be performed in this 
order because the mode field is a subfield of the flags longword. 


Initialize the pointers to the XTDB in the IXTCC and the pointer to 
the transport function table in the IXTCC. Inherit the event flag for 
I/O operations from the XTDB. 


@ Force the input and output operations to use SRPs for startup and 
disable free-input operations on the input LRP free queue. 


@® Remove an XTCB from the tail of the small input free queue. If the 
queue was empty or corrupted, return a bad queue status and leave 
the code path. 


@ Disable free-input operations on the input SRP free queue. Call 
DECW$XPORT_FREE_INPUT_BUFFER to start the first read 
operation on the connection, and return with the status. This is 
the successful end of the CONNECT code path. 


@ This code is entered as a result of leaving the CONNECT code path 
due to some problem. Deassign the channel, remove the IXTCC from 
the IXTCC queue header, and decrement the XTDB$L_REF_COUNT 
field that tracks the number of connections using this transport. 


The allocated memory will be deallocated by DECW$XPORT_OPEN. 


8.3.12 Sample XTFT$A_ATTACH_TRANSPORT Routine 
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The XTFT$A_ATTACH_TRANSPORT routine acts as an initialization 
procedure to perform any client- or server-specific operations required 
prior to establishing connections. 


Example 8-13 shows a sample implementation of the XTFT$A_ATTACH_ 
TRANSPORT routine. 


@ inet_dev_desc [0] 
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Example 8-13 Sample XTFT$A_ATTACH_TRANSPORT Routine 





GLOBAL ROUTINE DECWS$TCPIP_ ATTACH TRANSPORT ( tdb : REF $BBLOCK ) = 


BEGIN 

BIND 
iosb = tdb [xtdb$w_iosb] : VECTOR [4,WORD], 
xtpb = .tdb [xtdbSa_tpb] : $BBLOCK ; 

LABEL 
attach ; 

OWN 


socktype : INITIAL( (UCX$C_STREAM “ 16) + UCXSC_TCP ), 
sockaddrin : $BBLOCK [SINSS_ SOCKADDRIN] PRESET ( 
[SINSW_FAMILY] = INET$C_AF_ INET, 
[SINSW_PORT] 0, 
[SINSL_ADDR] swap_long( INET$C_INADDR_ANY )) : 


ll 


ll 


LOCAL 
sin_desc ;: VECTOR [2] INITIAL( SIN$S_SOCKADDRIN, sockaddrin ), 
log_desc : $BBLOCK [DSCS$S_DSCDEF1], 
tab_desc : $BBLOCK [DSC$S_DSCDEF1], 
items : BLOCKVECTOR [2, ITM$S_ITEM, 1], 
host_addr : VECTOR [16,BYTE,UNSIGNED], 
host_desc : VECTOR [2] INITIAL( %ALLOCATION( host_addr ) - 1, host_addr ), 
host_len : INITIAL( 0 ), 
stradr : REF VECTOR [,BYTE, UNSIGNED], 
Sinadr : REF VECTOR [,BYTE, UNSIGNED], 
strlen, 
func_code : INITIAL( INETACP_FUNCSC_GETHOSTBYNAME ), 
func_code_desc : VECTOR [2] INITIAL( *ALLOCATION( func_code ), func_code ), 
retlen, 
status ; 


SCHARCOUNT( inet_dev_str ) ; 
UPLIT( inet_dev_str ) ; 


inet_dev_desc [1] 


@tcpip tdb = .tdb 


tdb [xtdb$w_efn] = ASYNC_EFN ; 


© 1nn_desc [DSC$A_POINTER] = local_node ; 

items [0,ITMSW_ITMCOD] = LNM$ STRING ; 

items [0,ITM$W_BUFSIZ] = %ALLOCATION( local_node ) ; 
ocal node ; 


items [0,ITM$L_BUFADR] = fa 
= lnn_desc [DSCS$W_LENGTH] ; 


ni 
items (0, ITM$L_RETLEN] = 1 
items [1,ITM$W_ITMCOD] = 0 
items [1,ITM$W_BUFSIZ] = 0 
items [1,ITMS$L BUFADR] = 0 
items [1,ITM$L_RETLEN] = 0 ; 
log_desc [DSCSW_LENGTH] = sCHARCOUNT( inet_local_node ) 
log_desc [DSC$B_DTYPE] = DSC$K_DTYPE T ; 

log_desc [DSC$B_CLASS] = DSCS$K_CLASS_S ; 

log_desc [DSCSA_POINTER] = UPLIT( inet_local_node ) ; 
tab_desc [DSCS$W_LENGTH] = *CHARCOUNT( ’LNMSFILE DEV’ ) ; 
tab_desc [DSCSB_ DTYPE] = DSC$K_DTYPE T ; 

tab_desc [DSCSB CLASS] = DSC$K_CLASS S ; 

tab_desc [DSCSA_POINTER] = UPLIT( ’LNMSFILE DEV’ ) ; 


e §e Ne Of 


we 
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Example 8-13 (Cont.) Sample XTFT$A_ATTACH_TRANSPORT Routine 





status = $TRNLNM( TABNAM = tab_desc, 
LOGNAM = log_desc, 
ITMLST = items ) ; 
Qir ( .tdb [xtdb$v_mode] AND DECW$M_XPORT CLIENT ) NEQ 0 
THEN 
RETURN .status ; 
attach: 
BEGIN 
IF NOT .status 
THEN 
LEAVE attach; 
@ IF Not (status = $ASSIGN( DEVNAM = inet_dev_desc, 
CHAN = tdb [xtdb$w_chan], 
ACMODE = psl$c_user ) ) 
THEN 
LEAVE attach ; 
@ir (status = Sqiow ( EFN = .tdb [xtdb$w_efn], 
CHAN = .tdb [xtdb$w_chan], 
FUNC = I0$_ACPCONTROL, 
IOSB = iosb, 
Pl = func_code_desc, 
P2 = lnn_desc, 
P3 = host_len, 
P4 = host_desc ) ) 
THEN 
status = .iosb [0] ; 


IF NOT .status 


THEN 


LEAVE attach ; 


@ host_addr [.host_len] = %C’.’ ; 
host_desc [0] = .host_len +1 ; 


sina 


dr = sockaddrin [SIN$L_ADDR] 


INCR i FROM 0 TO 3 


DO 


IF CHSFAIL( strlen = CH$FIND_CH( .host_desc [0], .host_desc [1], %C’.’ ) ) 


BEGIN 
sinadr [.i] =0 ; 
stradr = .host_desc [1] ; 
THEN 
BEGIN 


status = SS$_BADPARAM ; 
LEAVE attach ; 
END ; 
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Example 8-13 (Cont.) Sample XTFT$A_ATTACH_TRANSPORT Routine 





strlen = .strlen - .stradr ; 

INCR j FROM 0 TO ( .strlen - 1 ) 

DO 
BEGIN 
sinadr [.i] = .sinadr [.i] * 10 + ( .stradr [.j] - %C’0’ ) ; 
END ; 


host_desc [1] = .host_desc [1] + .strlen +1 ; 
host_desc [0] = ( .host_desc [0] - .strlen ) - 1; 
IF ( .host_dese [0] LSS 0 ) 
THEN 

BEGIN 

status = SS$ BADPARAM ; 

LEAVE attach ; 

END ; 
END ; 


sockaddrin [SINSW_PORT] = swap_short( ( BASE_TCP_PORT + 
.xtpb [xtpb$w_display_num] ) ) ; 


@ir (status = S$Qrow( EFN = .tdb [xtdb$w_efn], 
CHAN = .tdb [xtdbSw_chan], 
FUNC = I0$_SETMODE, 
IOSB = iosb, 


Pl = socktype, 
P2 = ( %X’01000000’ OR INETS$M_LINGER OR INETS$M_KEEPALIVE ), 
P3 = sin_desc, 
P4=5) ) 

THEN 

status = .iosb [0] ; 
IF NOT .status 
THEN 


LEAVE attach ; 


Or not ( status = transport_read_queue( .tdb ) ) 
THEN 
LEAVE attach ; 


@ DECWSXPORT_ATTACHED( .tdb ) ; 
reattach_timer_ id = 0 ; 
RETURN SS$_NORMAL ; 

END ; 


@ detach _and_poll ( stdb ) ; 
RETURN .status ; 
END ; 





@ Create a suitable descriptor for the Internet device logical name string. 
The .address directive that would result from doing this at compile 
time cannot be fixed up by the image activator, so the descriptor is 
created at run time. 


@ Store the address of the XTDB that the common transport allocated 
for this transport in tcpip_tdb. References to this XTDB by the TCP/IP 
transport are usually made through this variable. Use event flag 31 
(ASYNC_EFWN) in asynchronous transport operations. 
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Get the string that represents the local system name in the Internet 
name space by translating the logical name “UCX$INET_HOST” that 
is generated by the local_node macro. 


If the transport is being attached by a client, no additional work is 
needed. A server continues processing to create a listener socket, 
among other things. 


Create a socket and assign a channel to the Internet networking 
service. This socket is owned by the specific transport and becomes the 
listener socket for all connection requests received from clients. 


Attempt to perform a name-to-address conversion for the local node 
with an IO$_ACPCONTROL $QIO system service that queries the 
UCX host database. The $QIO arguments are as follows: 


¢ The P1 argument specifies the control function that, in this case, 
requests a get-host-by-name conversion. P1 is the function to be 
performed by the IO$_ACPCONTROL $QIO. 


¢ P2 is the address of the descriptor of the local node name acquired 
at the beginning of this procedure. 


e¢ P93 is the address of a word to receive the length of the returned 
address string. 


e¢ P4 is the address of the descriptor of the storage to receive the 
address found by the search. 


Attempt to convert the ASCII Internet Standard Format address 
returned by the ACPCONTROL $QIO into the binary, 32-bit Network 
Standard Format address. (See Example 8-12.) 


To do this, convert numeric fields separated by periods into 1-byte 
values and then pack these bytes into a longword with the first- 
encountered field converted and inserted into the rightmost byte of the 
longword. For example, the address 130.180.40.44 would be converted 
to the longword value 2C28B482;¢. 


If there are too few fields, or any nonnumeric characters seen (other 
than the field separator), fail and indicate a bad parameter or invalid 
server name. 


If the conversion is successful, the Network Standard Format address 
is built in the sockaddrin structure. Determine which TCP port 
number to use to listen for client connection requests. Place this port 
number, in Network Standard Format, in the sockaddrin structure. 
(The port number is the result of adding the server number to 5000. 
In a “real” transport, this number would be 6000.) 


Establish the local address, port number, address family, and socket 
options on the listener socket. The $QIO arguments are as follows: 


e The Pl argument of the IO$_SETMODE $QIO system service is 
the address of a longword containing the protocol family and type 
to use (stream-mode, TCP socket). 


e The P2 argument sets various options for the socket (in this case, 
the linger and keep-alive TCP options). 
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¢ The P3 argument is the address of a descriptor of the sockaddrin 
structure that contains the address information for the socket. 


¢ The P5 argument is a nonzero value (specifically, 5) that marks 
the socket as a listener and sets the size of the connect queue. The 
connect queue limits the number of unacknowledged client connect 
requests that the Internet networking service is willing to retain. 


© Invoke the TRANSPORT_READ_QUEUE routine to start an 
asynchronous socket-accept operation. At this point, the server is 
capable of receiving connection requests from clients. 


@ Call DECW$XPORT_ATTACHED to report that the transport is 
attached. 


@® This code is entered only if something went wrong. Call the DETACH_ 
AND_POLL routine to deassign any channels and attempt to reattach 
to the network. 


8.3.13 Sample TRANSPORT_READ_QUEUE Routine 


The TRANSPORT_READ_QUEUE routine initiates an asynchronous 
connect-accept operation on the listener socket. Example 8-14 shows a 
sample implementation of the TRANSPORT_READ_QUEUE routine. 


Example 8-14 Sample TRANSPORT_READ_QUEUE Routine 


ROUTINE transport _read_queue( tdb : REF $BBLOCK ) = 
BEGIN 


LOCAL 
item3 : VECTOR [3], 
status ; 


@ Ir not .tdb [xtdb$v_dying] 
THEN 
BEGIN 


@ir Nor (status = $ASSIGN( DEVNAM = inet_dev_desc, 
CHAN = tdb [xtdb$w_acc_chan], 
ACMODE = psl$c_user ) ) 
THEN 

BEGIN 

tdb [xtdb$v_dying] = 1 ; 

RETURN .status 

END ; 
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Example 8-14 (Cont.) Sample TRANSPORT_READ_ QUEUE Routine 


© item3 [0] = xtdb$s_acc_inaddr ; 
item3 [1] = tdb [xtdb$t_acc_inaddr] ; 
item3 [2] = tdb [xtdb$l_acc_inaddr_len] ; 
@ status = $qio( EFN = .tdb [xtdb$w_efn], 
CHAN = .tdb [xtdb$w_chan], 
FUNC = IO$_ACCESS OR IO$M_ACCEPT, 
IOSB = tdb [xtdb$w_acc_iosb], 
ASTADR = transport_read_ast, 
ASTPRM = .tdb, 
P3 = item3, 
P4 = tdb [xtdb$w_acc_chan] ) ; 


IF NOT .status 

THEN 
BEGIN 
$DASSGN( CHAN = .tdb [xtdb$w_acc_chan] ) ; 
tdb [xtdb$v_dying] = 1 ; 
END 

END 

ELSE 
status = DECWS$_CNXABORT ; 


RETURN .status ; 
END ; 


@ Ifthe transport is dying, do not try to start another accept operation. 


@ Create a socket and assign a channel to the Internet networking 
service. If $ASSIGN fails, mark the transport as dying and quit. If 
successful, the channel number is stored in the XTDB$W_ACC_CHAN 
field of the XTDB, which is a field specific to this transport. 


© Create an item-list structure describing the area that is to receive 
information about the client that attempts to connect to the server. 
The first longword is the size of the area in bytes, the second is the 
address of the first byte, and the third is the address of a longword to 
receive the length of the data actually placed in the area. 


The item-list structure is allocated as a 16-byte field, XTDB$T_ACC_ 
INADDR, in the XTDB. XTDB$S_ACC_INADDR is the symbolic name 
for the length. 


@ Initiate an asychronous accept operation on the listener socket by 
means of the $QIO system service. The $QIO arguments are as 
follows: 


¢ The CHAN argument is the channel associated with the listener 
socket created in the XTFT$A_ATTACH_TRANSPORT routine. 
The specific transport uses this channel for connection requests 
from all clients. 


¢ The FUNC argument code is IO$_ACCESS with the IO$M_ 
ACCEPT modifier specified. 
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¢ The ASTADR argument is the AST completion routine to invoke 
on completion. TRANSPORT_READ_AST, which is described in 
Section 8.3.14, expects the address of the TCP/IP XTDB as its 
argument. . 


¢ The P3 argument is the address of the 3-longword item list 
previously described. The item list is used to store information 
about the connecting client’s node. 


e The P4 argument is the channel associated with the socket created 
on entry to TRANSPORT_READ_QUEUE. The server will use this 
channel for communication with the client. Each client connection 
is assigned its own channel. 


If the $QIO service failed, mark the transport as dying and release the 
channel. 


Sample TRANSPORT_READ_AST Routine 


TRANSPORT_READ_AST is invoked when the IO$_ACCESS $QIO issued 
by the TRANSPORT_READ_QUEUE routine completes and continues 
processing to fully establish the client connection. 


Example 8-15 shows a sample implementation of the TRANSPORT_ 
READ_AST routine. 


Example 8-15 Sample TRANSPORT_READ_AST Routine 


ROUTINE transport_read_ast( tdb : REF $BBLOCK ) : NOVALUE = 


BEGIN 
BUILTIN 
MOVPSL, 
REMQUE, 
INSQTI, 
INSQUE ; 
BIND 
xtpb = .tcpip_tdb [xtdb$a_tpb] : $BBLOCK, 
acc_iosb = tcpip_tdb [xtdb$w_acc_iosb] : VECTOR [4,WORD,UNSIGNED] ; 


LOCAL 
psl : $BBLOCK [4], 
found : INITIAL( 0 ), 
iosb : VECTOR [4,WORD,UNSIGNED] ; 


@ IF .acc_iosb. [0] EQL SS$_SHUT 


THEN 
BEGIN 
DECW$XPORT_ATTACH_LOST( .tdb , 0) ; 
detach_and_poll( .tdb ) ; 
RETURN ; 
END ; 


IF .acc_iosb [0] 
THEN 
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Example 8-15 (Cont.) Sample TRANSPORT_READ_AST Routine 





BEGIN 
MACRO 
ctrstr = ’!UB.!UB.!UB.!UB’ % ; 


LOCAL 
tceq : REF $BBLOCK INITIAL( 0 ), 
tcc : REF $BBLOCK INITIAL( 0 ), 
itcc : REF $BBLOCK INITIAL( 0 ), 
tcc_id : INITIAL( 0 ), 
tpb : REF $BBLOCK INITIAL( 0 ), 
fail : INITIAL( 1 ), 
status, 
il_count : INITIAL( .xtpb [xtpb$w_i_lrp count] 
is count : INITIAL( .xtpb [xtpb$w_i_srp_ count] 
ol_count : INITIAL( .xtpb [xtpb$w_o_lrp_ count] 
os_count : INITIAL( .xtpb [xtpb$w_o_srp_ count] 
at_tcb, 
tcb_count, 
tcb_array : REF VECTOR [] INITIAL( 0 ), 
func_code : INITIAL( INETACP_FUNCS$C_GETHOSTBYADDR ), 
func_code_desc : VECTOR [2] INITIAL( *ALLOCATION( func_code ), 

func_code ), 


— er 
~~ *- 3&8 ~ 


inaddr : S$BBLOCK [16], 
inaddr_len, ‘ 
inaddr_desc : VECTOR [2] INITIAL( *ALLOCATION( inaddr ), inaddr ), 
client desc : VECTOR [2], 
ctr_desc : VECTOR [2] INITIAL( *CHARCOUNT( ctrstr ), 

UPLIT( ctrstr ) ), 
info_size, 
info ptr, 
client_len ; 


LABEL 
connect ; 
2] connect: BEGIN 


info _size = INET NODE NAME LEN ; 
Or (itce = DECWSXPORT_ALLOC_PMEM( ixtcc$c_tcpip_ length, 
DECWSC_DYN_IXTCC )) EQLA 0 
THEN 
BEGIN 
status = SS$_INSFMEM ; 
LEAVE connect ; 
END 


IF (tpb = DECW$XPORT_ALLOC_PMEM( xtpb$c_tcpip_length, 
DECWSC_DYN_XTPB )) EQLA 0 
THEN 
BEGIN 
status = SS$_INSFMEM ; 
LEAVE connect ; 
END 


itec [ixtcc$a_tpb] = .tpb ; 
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Example 8-15 (Cont.) Sample TRANSPORT_READ_ AST Routine 





@ status = DECWSXPORT ALLOC_INIT QUEUES( .itcc, 
-tepip_tft[xtft$l_xtcc_length], 
-tpb [xtpb$Sw_srp_size], 
-tpb [xtpb$w_lrp_size], 
-tpb [xtpb$w_i_srp_ count], 
-tpb [xtpb$w_i_lrp count], 
-tpb [xtpb$w_o_srp count], 
-tpb [xtpb$w_o_lrp count], 
-info_size, 
info _ptr) ; 


IF NOT .status 
THEN 
LEAVE connect ; 


tcc = .itcc[ixtcc$a_tcc] ; 
inaddr_len = 0 ; 
@ IF Not (status = $FAO( ctr_desc, 
inaddr_len, 
inaddr_desc, 
-(tdb [xtdb$t_acc_inaddr]) <32,8,0>, 
-(tdb [{xtdb$t_acc_inaddr])<40,8,0>, 
-(tdb [xtdb$t_acc_inaddr])<48,8,0>, 
-(tdb [xtdb$t_acc_inaddr])<56,8,0> ) ) 
THEN 
BEGIN 
LEAVE connect ; 
END ; 


inaddr_desc [0] 
client_desc [0] 
client_desc [1] 
client_len = 0 ; 


-inaddr_len ; 
INET NODE NAME LEN - 1 ; 
eINLOl per +. 


OIF (status = SQIow( EFN = .tdb [xtdb$w_efn], 
CHAN = .tdb [xtdb$w_chan], 
FUNC = I0$ ACPCONTROL, 
IOSB = iosb, 
Pl = func_code_ desc, 
= inaddr_desc, 
P3 = client_len, 
P4 = client_desc ) ) 
THEN 
status = .iosb [0] ; 
IF NOT .status 
THEN 
BEGIN 
IF .status NEQU SS$_ENDOFFILE 
THEN 
BEGIN 
LEAVE connect ; 
END 
@ ELSE 
BEGIN 
CHSMOVE( .inaddr_len, .inaddr_desc [1], .client_desc [1] ) ; 
client_desc [0] = .inaddr_len ; 
client_len = .inaddr_len ; 
END ; 
END 
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Example 8-15 (Cont.) Sample TRANSPORT_READ_AST Routine 





@ ELSE 
BEGIN 
IF CHSEQL( .client_len, .client_desc [1], .1lnn_desc [DSCSW_LENGTH], 
-lnn_desc [DSCSA_POINTER], %C’ ’ ) 

THEN 
BEGIN 
(.client_desc [1])<0,8,0> = %C’0’ ; 
client_desc [0] =1; 
client_len = 1 ; 


END ; 
END ; 
eo 
(.info_ptr)<0,8,0> = %C’?’ 
@ ir -info_size GTR 0 
THEN 
BEGIN 
tee [xtcc$a_rem_user] = .info_ptr ; 
tec [xtcc$l_rem_user_len] =1;3 
tec [xtcc$a_rem_node] = .info_ ptr +1 ; 
tec [xtcc$l_rem_node_len] = .client_len ; 
END ; 
@ tcpip tdb {[xtdb$1_ref_count] = .tcpip tdb [xtdb$l_ref_ count] + 1 ; 
INSQUE( .itcc, tcpip_tdb [xtdb$a_itcc_flink] ) ; 
® itcc {ixtcc$w_chan] = .tcpip_tdb [xtdb$Sw_acc_chan] ; 
tepip_tdb [xtdb$w_acc_chan] = 0; 
®icc {xtcc$l_ flags] = xtcc$m_active ; 
tee [xtcc$v_mode] = DECWSK_XPORT_REMOTE_SERVER ; 
itce [ixtcc$w_efn] = .tcpip_tdb [xtdb$w_efn] ; 
itce [ixtcc$a_tdb] = .tcpip_tdb ; 
itce [ixtccSa_xport_table] = .tcepip_tdb [xtdb$a_xport_table] ; 
@ iF not (status = $DCLAST( ASTADR = transport_open_callback, 
ASTPRM = .itcc, 
ACMODE = psl$c_user ) ) 
THEN 
LEAVE connect ; 
® fail = 0; 
END ; 
@ir .fail 
THEN 
@ BEGIN 
IF .itcc NEQA 0 
THEN 
BEGIN 
IF .itec [ixtcc$w_chan] NEQU 0 
THEN 


SDASSGN( CHAN = .itcc [ixtcc$w_chan] ) ; 
REMQUE( .itcc, itcc ) ; 
tcpip_tdb [xtdb$l_ ref count] = .tcpip _tdb [xtdb$l_ref count] - 1; 
DECWSXPORT_DEALLOC_QUEUES( .itcc ) ; 
DECW$XPORT_DEALLOC_PMEM( .itcc ) ; 
END ; 
IF .tpb NEQA 0 
THEN 
DECWSXPORT_DEALLOC_PMEM( .tpb ) ; 
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Example 8-15 (Cont.) Sample TRANSPORT_READ_AST Routine 





DECWSXPORT ACCEPT FAILED ( .tcpip_tdb [xtdb$l_acc_inaddr_len], 
tcpip tdb [xtdb$t_acc_inaddr], 
-Status ) ; 
END ; 
END ; 


@® transport_read_queue ( -tcpip_tdb ) ; 
END ; 


@ Test the status from the IO$_ACCESS $QIO. If the network is 
shutting down, call DECW$XPORT_ATTACH_LOST to report that 
the transport shut down and then call DETACH_AND_POLL to poll 
for its return. If it was successful, continue processing to construct a 
full connection context. 


@ Start a named block of code that attempts to allocate and initialize 
the resources needed to maintain a connection. If any part of this 
setup fails, the code block is exited and failure processing recovers any 
allocated resources. 


© Allocate an IXTCC and XTPB for this connection. Store the address of 
the XTPB in the IXTCC. 


© Call the transport-common DECW$XPORT_ALLOC_INIT_QUEUES 
routine to allocate and initialize the communication queues. 
DECW$XPORT_ALLOC_INIT_QUEUES allocates a block of storage 
for an XTCC, XTCQ, and all of the XTCBs for a connection. 
DECW$XPORT_ALLOC_INIT_QUEUES must allocate at least an 
XTCC; the other structures are optional. DECW$XPORT_ALLOC_ 
INIT_QUEUES places all of the XTCBs on the appropriate free queues. 


© Convert the Network Standard Format Internet address of the 
connection client, which is returned by the IO$_ACCESS $QIO in 
the XTDB$T_ACC_INADDR field of the XTDB, into a dot-format 
Internet address. For example, the longword value 2C28B482;¢ would 
be converted to the ASCII string 130.180.40.44. 


© Attempt to perform address-to-nodename translation of the dot-format 
Internet address to get the textual name of the client node. The 
arguments of the IO$_ACPCONTROL $QIO system service are as 
follows: 


¢ P1 is the address of a 2-longword descriptor of a longword 
containing the function code INETACP_FUNC$C_ 
GETHOSTBYADDR. 


e 2 is the address of the descriptor of the dot-format Internet 
address to be translated. 


e P3 is the address of a word to receive the length of the resultant 
string. 
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e P4 is the address of a descriptor of an area of memory to receive 
the result of the translation. 


The address-to-nodename translation failed with the status of SS$_ 

ENDOFFILE. This indicates that the dot-address could not be found 
in the local host database. The dot-address form of the client’s node 
address will be used as the node name of the client. 


The address-to-nodename translation succeeded. Check if the returned 
node name matches the local node name. If it does, use the string “0” 
as the client’s node name; otherwise use the string returned by the 
translation operation. 


The Internet protocols do not support the concept of a remote user 
name. Synthesize this information by identifying the remote user with 
the string “?”. 


Point the XTCC to the remote-user name and node fields. 


Increment the reference count and insert the IXTCC on the XTDB so 
that the connection can be located during image rundown. 


Copy the channel assigned to the client connection into the IXTCC and 
zero this field in the XTDB. 


Mark the connection as active by setting the flags longword of the 
XTCC to the constant XTCC$M_ACTIVE and the connection mode 
as a remote server (these two operations should be performed in this 
order because the mode field is a subfield of the flags longword). 


Initialize the pointer to the XTDB in the IXTCC and the pointer to the 
transport function table in the IXTCC. Inherit the event flag for I/O 
operations from the XTDB. 


Deliver a user-mode AST to the TRANSPORT_OPEN_CALLBACK 
routine (with the IXTCC as the argument) to complete the connection 
acceptance in user mode. 


TRANSPORT_OPEN_CALLBACK performs the callback to the 
transport caller and starts I/O on the connection. 


Executive-mode connection setup completed. 


If any step of the connection setup in the connect block failed, resource 
recovery operations are performed here: channels are deassigned, 
memory is deallocated, connection structures are disassociated, 
reference counts are decremented, and so on. 


Call the transport common DECW$XPORT_ACCEPT_FAILED routine 
to generate a report describing the cause of the failure. 


@ This is the common exit point. Invoke TRANSPORT_READ_QUEUE 


to issue another IO$_ACCESS $QIO to receive another client 
connection request. 
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Sample TRANSPORT_OPEN_CALLBACK Routine 


TRANSPORT_OPEN_CALLBACK is invoked as a user-mode AST 
procedure by TRANSPORT_READ_AST to complete the creation of a 
connection. It performs a callback to the server’s connect-request routine 
and, depending on the value returned by that routine, completes the 
connection by starting the initial read operation. 


Example 8-16 shows a sample implementation of the TRANSPORT_ 
OPEN_CALLBACK routine. 


Example 8-16 Sample TRANSPORT_OPEN_CALLBACK Routine 





ROUTINE transport_open_callback( itcc : REF $BBLOCK ) : NOVALUE = 
BEGIN 
BUILTIN 
REMOQTI ; 
LOCAL 
tee: REF $BBLOCK INITIAL ( .itce [ixtcc$a_tec] ), 
free queue: REF VECTOR[2], 
status ; 


LABEL 
start_reading ; 


start_reading: 

BEGIN 

OIF NoT (status = (.tcpip_tdb [xtdb$a_connect_request])( .tcc )) 
THEN 

LEAVE start_reading ; 

@ xport_in state_srp( Eee.) 3 
xport_out_state_srp( tcc ) ; 
xport_in_free_disable( tcc, decwSc_xport_buffer_lrp ) ; 


© free queue = .tcc [xtcc$a_ifs queue] ; 

IF .free queue[0] EQLA 0 

THEN 
BEGIN 
free_queue = .tcc [xtcc$a_ifl_queue] ; 
IF .free_queue[0] EQLA 0 
THEN 

BEGIN 


status = DECW$_BADQUEUE ; 
LEAVE start_reading ; 
END ; 

END ; 


@ status = DECWS$TCPIP_EXECUTE_FREE 
( .tcec, 0, decwSc_xport_buffer_srp, .free_queue ) ; 
IF .status 
THEN 
RETURN ; 
END ; 


© DECWSXPORT_CLOSE( .tcc ) ; 
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© DECWSxPORT_REFUSED BY SERVER ( .status ) ; 


RETURN ; 
END ; 


Invoke the server’s connect-request routine with the address of the 
XTCC for the connection. 


@ The transport user accepted the connection. Force the input and 


output operations to use small request packets for startup and disable 
free-input operations on the input large request packet free queue. 


Check the small input free queue and, if it is empty, the large input 
free queue. If both are empty, the transport cannot perform a read 
operation, so return a bad queue status. 


Call the XTFT$A_EXECUTE_FREE routine to put the buffers on the 
free queue and return. 


This code is entered only if the callback procedure returned a failure 
status. Invoke the transport-common DECW$XPORT_CLOSE routine 
to complete the destruction of the connection. 


Call DECW$XPORT_REFUSED_BY_SERVER to format and deliver a 
message vector to describe the reason for the connection refusal. This 
is constructed on the status code returned by the callback procedure. 


8.3.16 Sample DETACH_AND_POLL Routine 


DETACH_AND_POLL starts polling for a transport restart. 


Example 8-17 shows a sample implementation of the DETACH_AND_ 
POLL routine. 


| 
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Example 8-17 Sample DETACH_AND POLL Routine 





ROUTINE detach_and_poll( tdb : REF $BBLOCK ) : NOVALUE = 
BEGIN 
BUILTIN 
EMUL ; 
LOCAL 
status ; 
@ ir .tdb [xtdb$v_dying] 
THEN 
RETURN ; 
@Ir .tdb [xtdb$w_chan] NEQ 0 
THEN 
BEGIN 


SCANCEL( CHAN -tdb [xtdb$w_chan] ) ; 
SDASSGN( CHAN -tdb [xtdbSw_chan] ) ; 
tdb [xtdb$Sw_chan] = 0 ; 

END ; 


Or .tdb [xtdb$w_acc_chan] NEQ 0 
THEN 
BEGIN 
SCANCEL( CHAN -tdb [xtdb$w_acc_chan] ) ; 
SDASSGN( CHAN .tdb [xtdb$w_acc_chan] ) ; 
tdb [xtdb$w_acc_chan] = 0 ; 
END ; 


| 


Or -reattach_ timer id EQL 0 
THEN 
BEGIN 
reattach_timer_ id = .tdb ; 
EMUL( %REF( REATTACH INTERVAL _ SECS ), %REF( -10000000 ), %REF( 0 ), 
reattach_timer_ delta ) ; 


END ; 
@ir .tcpip tdb [xtdb$v_dying] 
THEN 
RETURN ; 
@ status = $SETIMR ( 
EFN = 31, 
DAYTIM = reattach _timer_delta, 
ASTADR = reattach ast, 
REQIDT = .reattach_timer_id ) ; 
@ ir nor .status 
THEN 
DECWSXPORT_REATTACH_FAILED( .tdb, .status ) ; 
RETURN ; 


END ; 





@ Ifthe XTDB$V_DYING bit is set, there is no need to continue. 
@ Release the channel to the Internet device. 


© Release the connection-accept channel. 
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If the timer is not identified, associate the timer with the address of 
the XTDB. 


14) 
@ Make sure that the transport is still alive. 
6) 
7) 


Start polling for a network restart at reattach_timer_delta intervals. 
(The REATTACH_AST routine is described in Section 8.3.17.) 


If unable to poll for the restart, report that the reattach failed. 


8.3.17 Sample REATTACH_AST Routine 


REATTACH_AST calls DECW$$TCPIP_ATTACH_TRANSPORT to 
reattach the transport when the reattach_timer_delta interval has 
expired. 


Example 8-18 shows a sample implementation of the REATTACH_AST 
routine. 


Example 8-18 Sample REATTACH_AST Routine 


ROUTINE reattach_ast( tdb : REF $BBLOCK ) : NOVALUE = 
BEGIN 


LOCAL 
status; 
@ status = DECWSSTCPIP_ATTACH_TRANSPORT ( etdb ) ; 


RETURN ; 
END ; 


@ Call DECW$$TCPIP_ATTACH_TRANSPORT to reattach the 
transport. 


8.3.18 Sample XTFT$A_RUNDOWN Routine 


XTFT$A_RUNDOWN is invoked by the common transport when the 
image in which the transport is running exits. It is the responsibility of 
each transport’s rundown procedure to release any resources that might 
survive the image exit. ASTs are disabled while XTFT$A_RUNDOWN is 
executing. 


Example 8-19 shows a sample implementation of the XTFT$A_ 
RUNDOWN routine. 
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Example 8-19 Sample XTFT$A_RUNDOWN Routine 


GLOBAL ROUTINE DECWS$TCPIP_RUNDOWN ( tdb : REF $BBLOCK ) : NOVALUE = 


BEGIN 
BIND 
iosb = tdb [xtdb$w_iosb] : VECTOR [4,WORD], 
xtpb = .tdb [xtdbSa_tpb] : $BBLOCK ; 
LOCAL 
itcc : REF $BBLOCK INITIAL( .tdb [xtdb$a_itcc_flink] ), 
status ; 


Oita [xtdb$v_dying] = 1 ; 


@ WHILE .itcc NEQA tdb [xtdb$a_itcc flink] DO 


BEGIN 
BIND 
xtcc = .itcc [ixtec$a_tcc] : $BBLOCK ; 
xtcce [xtcc$v_dying] = 1; 
SCANCEL ( CHAN = .itcc [ixtcc$w_chan] ) ; 
SDASSGN ( CHAN = .itcc [ixtcc$w_chan] ) ; 
itce [ixtcc$w_chan] = 0 ; 
itce = .itcce [xtcc$a_flink] ; 
END ; 
Or ( .tdb [xtdb$v_mode] AND DECW$M_XPORT CLIENT ) NEQ 0 
THEN 
RETURN ; 


@ scaNcEL( CHAN 
SCANCEL( CHAN 


SDASSGN( CHAN = .tdb [xtdb$w_acc_chan] ) ; 
tdb [xtdb$w_acc_chan] = 0 ; 

SDASSGN ( CHAN = .tdb [xtdbSw_chan] ) ; 
tdb [xtdb$Sw_chan] = 0 ; 


IF .reattach_timer_id NEQ 0 
THEN 
SCANTIM( REQIDT = .reattach_timer_id ) ; 


-tdb [xtdb$w_chan] ) ; 
-tdb [xtdb$w_acc_chan] ) ; 


RETURN ; 
END ; 





@ Mark this transport as dying to prevent any of the routines, such as 
TRANSPORT_READ_QUEUE, from performing additional operations. 


@ Locate each connection known to this transport and perform any 
rundown operations necessary. For TCP/IP, the connection is marked 
as dying to prevent any per-connection routine from operating on 
the connection. Any I/O operation in progress on the connection is 
canceled and the communication channel is deassigned. 


© Ifthe caller is a client, no more processing is needed for rundown. 
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© For servers, cancel any I/O operation on the listening and accepting 
channels and deassign the channels. 


8.3.19 Sample DECW$TRANSPORT_INIT Routine 


The DECW$TRANSPORT_INIT routine initializes and returns the 
address of the XTFT. Each specific transport has a global symbol 
named DECW$TRANSPORT_INIT. This is the address of the first 
procedure invoked in the specific transport during the common transport 
DECW$XPORT_ATTACH_TRANSPORT routine and it is responsible for 
initializing the fields in the XTFT structure. 


The DECW$EXAMPLES:XPORT_EXAMPLE_XFER.MAR module and 
DECW$EXAMPLES:DEMO_BUILD.COM procedure ensure that the 
transfer vector to the DECW$TRANSPORT_INIT routine is found at the 
beginning of the transport-specific shareable image. 


Unlike the other transport-specific functions, DECW$TRANSPORT_INIT 
returns the address of the XTFT structure as its return value instead of a 
VMS condition code. 


Example 8-20 shows a sample implementation of the 
DECW$TRANSPORT_INIT routine. 


Example 8-20 Sample DECWS$TRANSPORT_INIT Routine 


GLOBAL ROUTINE DECWSTRANSPORT_INIT = 


BEGIN 
LOCAL 
tit: REF SBBLOCK ; 


tit = tepip tre ; 

tft[xtf£t$l_ requiredO] = xtft$k_required0d ; 

tft[xtft$l_ reserved0] = 0 ; 

tft [xtft$a_execute_write] = decw$$tcpip execute write ; 
tft[xtftSa_write] = decw$$tcpip write ; 
tft[xtft$a_write user] = decw$$tcpip write_user ; 

tft [xtft$a_execute_free] = decw$$tcpip execute free ; 
tft(xtit$a_free input_buffer] = decw$Stcpip free _input_buffer ; 
tft [xtft$a_close] = decw$$tcpip_close ; 

tfit[xtftSa_open] = decwS$tcpip_open ; 
tfit(xtftSa_attach_transport] = decw$$tcpip_attach_transport ; 
tft [xtftS$a_rundown] = decw$$tcpip rundown ; 

tft [xtf£t$l_xtcc_length] = xtcc$c_tcpip_ length ; 

tft [xtft$l_xtpb length] xtpb$c_tcpip length ; 

tft [xtf£t$l_xtdb length] xtdb$c_tcpip length ; 
tft[xtft$l_ixtcc_length] = ixtcc$c_tcpip length ; 
tft[xtft$l_required1] = xtft$k_requiredl ; 

etit 

END ; 


8-50 
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DECW$EXAMPLES:XPORT_EXAMPLE_XFER.MAR generates transfer 
vectors for the sample transport. A portion of the XPORT_EXAMPLE_ 
XFER.MAR code follows: 


-PSECT $TRANSFERS PIC,USR, CON, REL, LCL, SHR, EXE, RD, NOWRT, QUAD 
TRANSFER DECWSTRANSPORT_INIT 
. END 


The $TRANSFER$ program section points to a program unit, in this case 
DECW$TRANSPORT_INIT. The DEMO_BUILD.COM procedure then 
creates a cluster and collects the $TRANSFER$ program section in it, as 
described in Example 8-1. 
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